@xexr/blog-platform 1.0.6 → 1.0.8

package/dist/lib/version.ts

@@ -0,0 +1,154 @@
+// Import package.json for version info (works with resolveJsonModule)
+import packageJson from "../../package.json";
+
+/**
+ * Version information
+ */
+export interface VersionInfo {
+  name: string;
+  version: string;
+  major: number;
+  minor: number;
+  patch: number;
+}
+
+/**
+ * Version compatibility result
+ */
+export interface VersionCompatibilityResult {
+  compatible: boolean;
+  errorCode?: string;
+  errorMessage?: string;
+  warning?: string;
+}
+
+/**
+ * Version compatibility error codes (matches PRD error codes)
+ */
+export const VERSION_ERROR_CODES = {
+  PUB009: "Major version incompatibility",
+  PUB010: "Minor version warning",
+} as const;
+
+/**
+ * Parse semantic version string into components
+ * @param version - Version string (e.g., "1.2.3")
+ * @returns Parsed version components
+ */
+function parseVersion(version: string): { major: number; minor: number; patch: number } {
+  const cleaned = version.replace(/^v/, ""); // Remove 'v' prefix if present
+  const parts = cleaned.split(".");
+  
+  if (parts.length < 3) {
+    throw new Error(`Invalid version format: ${version}`);
+  }
+  
+  const major = parseInt(parts[0] ?? "0", 10);
+  const minor = parseInt(parts[1] ?? "0", 10);
+  const patch = parseInt(parts[2]?.split("-")[0] ?? "0", 10); // Handle pre-release versions
+  
+  if (isNaN(major) || isNaN(minor) || isNaN(patch)) {
+    throw new Error(`Invalid version format: ${version}`);
+  }
+  
+  return { major, minor, patch };
+}
+
+/**
+ * Get blog platform package version (current package)
+ * @returns Blog platform version information
+ */
+export function getBlogPlatformVersion(): VersionInfo {
+  // Use imported package.json (works reliably in both CJS and ESM)
+  const versionComponents = parseVersion(packageJson.version);
+
+  return {
+    name: packageJson.name,
+    version: packageJson.version,
+    ...versionComponents,
+  };
+}
+
+/**
+ * Parse version header from incoming request
+ * Expected format: "bloggy/1.0.0 platform/1.0.0"
+ * @param headerValue - Version header value
+ * @returns Parsed version information or null if invalid
+ */
+export function parseVersionHeader(headerValue: string): {
+  bloggyVersion?: VersionInfo;
+  platformVersion?: VersionInfo;
+} | null {
+  try {
+    const parts = headerValue.split(" ");
+    const result: { bloggyVersion?: VersionInfo; platformVersion?: VersionInfo } = {};
+    
+    for (const part of parts) {
+      const [name, version] = part.split("/");
+      if (!name || !version) continue;
+      
+      const versionComponents = parseVersion(version);
+      const versionInfo: VersionInfo = {
+        name: name,
+        version: version,
+        ...versionComponents,
+      };
+      
+      if (name === "bloggy") {
+        result.bloggyVersion = versionInfo;
+      } else if (name === "platform") {
+        result.platformVersion = versionInfo;
+      }
+    }
+    
+    return result;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Check version compatibility between two versions
+ * Based on semantic versioning rules:
+ * - Major version differences are incompatible (PUB009)
+ * - Minor version differences are warnings (PUB010)
+ * - Patch version differences are acceptable
+ * 
+ * @param version1 - First version
+ * @param version2 - Second version
+ * @returns Compatibility result
+ */
+export function checkVersionCompatibility(
+  version1: VersionInfo,
+  version2: VersionInfo,
+): VersionCompatibilityResult {
+  try {
+    // Major version incompatibility
+    if (version1.major !== version2.major) {
+      return {
+        compatible: false,
+        errorCode: "PUB009",
+        errorMessage: `Major version incompatibility: ${version1.name} ${version1.version} is not compatible with ${version2.name} ${version2.version}. Please upgrade.`,
+      };
+    }
+    
+    // Minor version warning
+    if (version1.minor !== version2.minor) {
+      return {
+        compatible: true,
+        errorCode: "PUB010",
+        warning: `Minor version difference: ${version1.name} ${version1.version} with ${version2.name} ${version2.version}. Some features may not be available.`,
+      };
+    }
+    
+    // Compatible (same major.minor, patch differences are okay)
+    return {
+      compatible: true,
+    };
+  } catch (error) {
+    return {
+      compatible: false,
+      errorMessage: `Failed to check version compatibility: ${error instanceof Error ? error.message : "Unknown error"}`,
+    };
+  }
+}

package/dist/types/contracts.ts

@@ -0,0 +1,256 @@
+/**
+ * Public API contracts for the @xexr/blog-platform package.
+ *
+ * These types define the public interface between Bloggy and external blog platforms.
+ * They must remain stable and backward-compatible to ensure smooth upgrades.
+ *
+ * IMPORTANT: These contracts should never import from the main Bloggy application
+ * to maintain clean separation of concerns and prevent coupling.
+ */
+
+/**
+ * Public profile and social links for an author.
+ */
+export interface PublishedAuthorSocialLinks {
+  /** Author website or profile URL */
+  readonly website?: string;
+
+  /** X/Twitter profile URL */
+  readonly x?: string;
+
+  /** LinkedIn profile URL */
+  readonly linkedin?: string;
+
+  /** GitHub profile URL */
+  readonly github?: string;
+
+  /** Public contact email address */
+  readonly email?: string;
+}
+
+/**
+ * Represents a published author with essential information for bylines and attribution.
+ */
+export interface PublishedAuthor {
+  /** Unique identifier for the author */
+  readonly id: string;
+
+  /** Author's full name */
+  readonly name: string;
+
+  /** URL-friendly slug for author pages */
+  readonly slug: string;
+
+  /** Author's bio/description (optional) */
+  readonly bio?: string;
+
+  /** Author avatar image URL (optional) */
+  readonly avatarUrl?: string;
+
+  /** Public profile and social links (optional) */
+  readonly socialLinks?: PublishedAuthorSocialLinks;
+
+  /** Pronouns for proper attribution */
+  readonly pronouns?: string;
+
+  /** Whether this is a guest author */
+  readonly isGuest: boolean;
+
+  /** Tone adjectives that describe this author's writing style */
+  readonly toneAdjectives: readonly string[];
+}
+
+/**
+ * Represents a published site with essential metadata for blog rendering.
+ */
+export interface PublishedSite {
+  /** Unique identifier for the site */
+  readonly id: string;
+
+  /** Site name/title */
+  readonly name: string;
+
+  /** Site tagline/subtitle */
+  readonly tagline: string;
+
+  /** Site description */
+  readonly description: string;
+
+  /** Primary domain for the site */
+  readonly domain: string;
+
+  /** Site-wide tone adjectives for content context */
+  readonly toneAdjectives: readonly string[];
+
+  /** Default locale/language code */
+  readonly locale: string;
+}
+
+/**
+ * Public topic/category taxonomy assigned to published articles.
+ */
+export interface PublishedTopic {
+  /** Unique identifier for the topic */
+  readonly id: string;
+
+  /** Display name */
+  readonly name: string;
+
+  /** URL-friendly slug for topic archive routing */
+  readonly slug: string;
+
+  /** Optional public description */
+  readonly description?: string;
+
+  /** Whether this is the article's primary topic */
+  readonly isPrimary: boolean;
+}
+
+/**
+ * Represents a published article with all necessary metadata for rendering
+ * on external blog platforms.
+ */
+export interface PublishedArticle {
+  /** Unique identifier for the article */
+  readonly id: string;
+
+  /** URL-friendly slug for routing */
+  readonly slug: string;
+
+  /** Article title/headline */
+  readonly title: string;
+
+  /** Brief excerpt/summary for meta descriptions and previews */
+  readonly excerpt: string;
+
+  /** Full article content in markdown format */
+  readonly content: string;
+
+  /** Estimated reading time in seconds */
+  readonly readingSeconds: number;
+
+  /** Word count for analytics */
+  readonly wordCount: number;
+
+  /** Publication date as ISO 8601 string */
+  readonly publishedAt: string;
+
+  /** Last updated date as ISO 8601 string */
+  readonly updatedAt: string;
+
+  /** Author information (can be null for anonymous posts) */
+  readonly author: PublishedAuthor | null;
+
+  /** Site information */
+  readonly site: PublishedSite;
+
+  /** Public topic taxonomy assigned to the article */
+  readonly topics?: readonly PublishedTopic[];
+
+  /** Featured image URL (optional) */
+  readonly featuredImage?: string;
+
+  /** Alt text for featured image */
+  readonly featuredImageAlt?: string;
+
+  /** Featured image R2 key for CDN optimization (optional) */
+  readonly featuredImageKey?: string;
+
+  /** SEO meta tags */
+  readonly meta: {
+    /** Meta title (defaults to article title if not provided) */
+    readonly title?: string;
+
+    /** Meta description (defaults to excerpt if not provided) */
+    readonly description?: string;
+
+    /** Canonical URL for SEO */
+    readonly canonicalUrl?: string;
+
+    /** Keywords for SEO */
+    readonly keywords: readonly string[];
+
+    /** Open Graph image URL */
+    readonly ogImage?: string;
+  };
+
+  /** Article version for optimistic locking */
+  readonly version: number;
+}
+
+/**
+ * Payload structure for publishing operations.
+ * Used when sending publish/unpublish requests to blog platforms.
+ */
+export interface PublishPayload {
+  /** The article to publish */
+  readonly article: PublishedArticle;
+
+  /** Idempotency key to prevent duplicate operations */
+  readonly idempotencyKey: string;
+
+  /** Optional slug override (defaults to article.slug) */
+  readonly slug?: string;
+
+  /** Optional meta description override (defaults to article.excerpt) */
+  readonly metaDescription?: string;
+
+  /** Platform-specific configuration */
+  readonly platformConfig?: Record<string, unknown>;
+
+  /** Whether this is a dry run (validation only) */
+  readonly dryRun?: boolean;
+}
+
+/**
+ * Result structure returned from publishing operations.
+ */
+export interface PublishResult {
+  /** Whether the operation was successful */
+  readonly success: boolean;
+
+  /** The published article URL if successful */
+  readonly url?: string;
+
+  /** Platform-specific post ID */
+  readonly platformPostId?: string;
+
+  /** Publication timestamp as ISO 8601 string */
+  readonly publishedAt?: string;
+
+  /** Error information if unsuccessful */
+  readonly error?: {
+    /** Error code (PUB001-PUB011) */
+    readonly code: string;
+
+    /** Human-readable error message */
+    readonly message: string;
+
+    /** Additional error details */
+    readonly details?: Record<string, unknown>;
+  };
+
+  /** Validation warnings (for dry runs or minor issues) */
+  readonly warnings?: readonly string[];
+
+  /** Idempotency key used for this operation */
+  readonly idempotencyKey: string;
+}
+
+/**
+ * Payload structure for unpublishing operations.
+ * Used when sending unpublish requests to blog platforms.
+ */
+export interface UnpublishPayload {
+  /** The slug of the article to unpublish */
+  readonly slug: string;
+
+  /** Idempotency key to prevent duplicate operations */
+  readonly idempotencyKey: string;
+
+  /** Platform-specific configuration */
+  readonly platformConfig?: Record<string, unknown>;
+
+  /** Whether this is a dry run (validation only) */
+  readonly dryRun?: boolean;
+}

package/dist/types/index.d.mts

@@ -7,6 +7,21 @@
  * IMPORTANT: These contracts should never import from the main Bloggy application
  * to maintain clean separation of concerns and prevent coupling.
  */
+/**
+ * Public profile and social links for an author.
+ */
+interface PublishedAuthorSocialLinks {
+    /** Author website or profile URL */
+    readonly website?: string;
+    /** X/Twitter profile URL */
+    readonly x?: string;
+    /** LinkedIn profile URL */
+    readonly linkedin?: string;
+    /** GitHub profile URL */
+    readonly github?: string;
+    /** Public contact email address */
+    readonly email?: string;
+}
 /**
  * Represents a published author with essential information for bylines and attribution.
  */
@@ -19,6 +34,10 @@ interface PublishedAuthor {
     readonly slug: string;
     /** Author's bio/description (optional) */
     readonly bio?: string;
+    /** Author avatar image URL (optional) */
+    readonly avatarUrl?: string;
+    /** Public profile and social links (optional) */
+    readonly socialLinks?: PublishedAuthorSocialLinks;
     /** Pronouns for proper attribution */
     readonly pronouns?: string;
     /** Whether this is a guest author */
@@ -45,6 +64,21 @@ interface PublishedSite {
     /** Default locale/language code */
     readonly locale: string;
 }
+/**
+ * Public topic/category taxonomy assigned to published articles.
+ */
+interface PublishedTopic {
+    /** Unique identifier for the topic */
+    readonly id: string;
+    /** Display name */
+    readonly name: string;
+    /** URL-friendly slug for topic archive routing */
+    readonly slug: string;
+    /** Optional public description */
+    readonly description?: string;
+    /** Whether this is the article's primary topic */
+    readonly isPrimary: boolean;
+}
 /**
  * Represents a published article with all necessary metadata for rendering
  * on external blog platforms.
@@ -72,6 +106,8 @@ interface PublishedArticle {
     readonly author: PublishedAuthor | null;
     /** Site information */
     readonly site: PublishedSite;
+    /** Public topic taxonomy assigned to the article */
+    readonly topics?: readonly PublishedTopic[];
     /** Featured image URL (optional) */
     readonly featuredImage?: string;
     /** Alt text for featured image */
@@ -139,4 +175,4 @@ interface PublishResult {
     readonly idempotencyKey: string;
 }
 
-export type { PublishPayload, PublishResult, PublishedArticle, PublishedAuthor, PublishedSite };
+export type { PublishPayload, PublishResult, PublishedArticle, PublishedAuthor, PublishedAuthorSocialLinks, PublishedSite, PublishedTopic };

package/dist/types/index.d.ts

@@ -7,6 +7,21 @@
  * IMPORTANT: These contracts should never import from the main Bloggy application
  * to maintain clean separation of concerns and prevent coupling.
  */
+/**
+ * Public profile and social links for an author.
+ */
+interface PublishedAuthorSocialLinks {
+    /** Author website or profile URL */
+    readonly website?: string;
+    /** X/Twitter profile URL */
+    readonly x?: string;
+    /** LinkedIn profile URL */
+    readonly linkedin?: string;
+    /** GitHub profile URL */
+    readonly github?: string;
+    /** Public contact email address */
+    readonly email?: string;
+}
 /**
  * Represents a published author with essential information for bylines and attribution.
  */
@@ -19,6 +34,10 @@ interface PublishedAuthor {
     readonly slug: string;
     /** Author's bio/description (optional) */
     readonly bio?: string;
+    /** Author avatar image URL (optional) */
+    readonly avatarUrl?: string;
+    /** Public profile and social links (optional) */
+    readonly socialLinks?: PublishedAuthorSocialLinks;
     /** Pronouns for proper attribution */
     readonly pronouns?: string;
     /** Whether this is a guest author */
@@ -45,6 +64,21 @@ interface PublishedSite {
     /** Default locale/language code */
     readonly locale: string;
 }
+/**
+ * Public topic/category taxonomy assigned to published articles.
+ */
+interface PublishedTopic {
+    /** Unique identifier for the topic */
+    readonly id: string;
+    /** Display name */
+    readonly name: string;
+    /** URL-friendly slug for topic archive routing */
+    readonly slug: string;
+    /** Optional public description */
+    readonly description?: string;
+    /** Whether this is the article's primary topic */
+    readonly isPrimary: boolean;
+}
 /**
  * Represents a published article with all necessary metadata for rendering
  * on external blog platforms.
@@ -72,6 +106,8 @@ interface PublishedArticle {
     readonly author: PublishedAuthor | null;
     /** Site information */
     readonly site: PublishedSite;
+    /** Public topic taxonomy assigned to the article */
+    readonly topics?: readonly PublishedTopic[];
     /** Featured image URL (optional) */
     readonly featuredImage?: string;
     /** Alt text for featured image */
@@ -139,4 +175,4 @@ interface PublishResult {
     readonly idempotencyKey: string;
 }
 
-export type { PublishPayload, PublishResult, PublishedArticle, PublishedAuthor, PublishedSite };
+export type { PublishPayload, PublishResult, PublishedArticle, PublishedAuthor, PublishedAuthorSocialLinks, PublishedSite, PublishedTopic };

package/dist/types/index.ts

@@ -0,0 +1,16 @@
+/**
+ * Public type exports for @xexr/blog-platform
+ *
+ * This file provides clean imports for all public API contracts.
+ * These types define the interface between Bloggy and blog platforms.
+ */
+
+export type {
+  PublishedArticle,
+  PublishedAuthor,
+  PublishedAuthorSocialLinks,
+  PublishedSite,
+  PublishedTopic,
+  PublishPayload,
+  PublishResult,
+} from "./contracts";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xexr/blog-platform",
-  "version": "1.0.6",
+  "version": "1.0.8",
   "description": "SEO-friendly blog platform for Next.js 15 with Bloggy integration",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -15,6 +15,11 @@
       "import": "./dist/types/index.mjs",
       "require": "./dist/types/index.js"
     },
+    "./app/blog/[slug]/page": {
+      "types": "./dist/app/blog/[slug]/page.d.ts",
+      "import": "./dist/app/blog/[slug]/page.tsx",
+      "default": "./dist/app/blog/[slug]/page.tsx"
+    },
     "./app/*": "./dist/app/*",
     "./styles/*": "./dist/styles/*"
   },
@@ -25,13 +30,6 @@
     "CHANGELOG.md"
   ],
   "license": "MIT",
-  "scripts": {
-    "build": "tsup",
-    "test": "vitest",
-    "lint": "eslint src --max-warnings 0",
-    "typecheck": "tsc --noEmit",
-    "prepublishOnly": "pnpm run build"
-  },
   "peerDependencies": {
     "@libsql/client": "^0.15.0",
     "drizzle-orm": "^0.44.0",
@@ -49,6 +47,7 @@
     "date-fns": "^4.1.0",
     "lucide-react": "^1.11.0",
     "next-mdx-remote-client": "^2.1.10",
+    "react-icons": "^5.6.0",
     "rehype-slug": "^6.0.0",
     "remark-gfm": "^4.0.1",
     "remark-toc": "^9.0.0",
@@ -59,5 +58,11 @@
     "tsup": "^8.5.1",
     "typescript": "^5.9.3",
     "vitest": "^4.1.5"
+  },
+  "scripts": {
+    "build": "tsup && node scripts/copy-dist-assets.mjs",
+    "test": "vitest",
+    "lint": "eslint src --max-warnings 0",
+    "typecheck": "tsc --noEmit"
   }
-}
+}