@foliokit/cms-core 1.0.0 → 1.0.1

package/src/lib/services/post.service.spec.ts

@@ -0,0 +1,255 @@
+import { TestBed } from '@angular/core/testing';
+import { lastValueFrom } from 'rxjs';
+import {
+  collection,
+  doc,
+  getDoc,
+  getDocs,
+  orderBy,
+  query,
+  setDoc,
+  Timestamp,
+  updateDoc,
+} from 'firebase/firestore';
+import { deleteObject, ref } from 'firebase/storage';
+import { FIREBASE_STORAGE, FIRESTORE } from '../firebase/firebase.config';
+import { PostService } from './post.service';
+import {
+  fakeTimestamp,
+  firestoreStub,
+  makeBlogPost,
+  mockDocSnapshot,
+  mockQuerySnapshot,
+} from '../../../testing/firestore.stub';
+
+// ---------------------------------------------------------------------------
+// Module mocks — hoisted before all imports by Vitest.
+// Replaces every firebase SDK export with vi.fn() so the real SDK
+// is never imported or initialised.
+// ---------------------------------------------------------------------------
+vi.mock('firebase/firestore', () => ({
+  collection: vi.fn(() => ({})),
+  doc: vi.fn(() => ({ id: 'generated-xyz' })),
+  getDoc: vi.fn(),
+  getDocs: vi.fn(),
+  setDoc: vi.fn(),
+  updateDoc: vi.fn(),
+  query: vi.fn((ref: unknown) => ref),
+  orderBy: vi.fn((...args: unknown[]) => args),
+  where: vi.fn((...args: unknown[]) => args),
+  limit: vi.fn((n: number) => n),
+  Timestamp: {
+    now: vi.fn(() => fakeTimestamp),
+    fromMillis: vi.fn(() => fakeTimestamp),
+  },
+}));
+
+vi.mock('firebase/storage', () => ({
+  ref: vi.fn(() => ({})),
+  deleteObject: vi.fn(),
+}));
+
+describe('PostService', () => {
+  let service: PostService;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+
+    // collection always returns an opaque ref object; doc and query pass it through
+    vi.mocked(collection).mockReturnValue({} as ReturnType<typeof collection>);
+    vi.mocked(doc).mockReturnValue({ id: 'generated-xyz' } as ReturnType<typeof doc>);
+    vi.mocked(query).mockImplementation((ref) => ref as ReturnType<typeof query>);
+
+    TestBed.configureTestingModule({
+      providers: [
+        PostService,
+        { provide: FIRESTORE, useValue: firestoreStub },
+        { provide: FIREBASE_STORAGE, useValue: {} },
+      ],
+    });
+
+    service = TestBed.inject(PostService);
+  });
+
+  // -------------------------------------------------------------------------
+  describe('getPostById', () => {
+    it('returns the mapped BlogPost when the document exists', async () => {
+      const raw = {
+        slug: 'hello',
+        title: 'Hello World',
+        status: 'draft',
+        content: '',
+        tags: [],
+        embeddedMedia: {},
+        seo: {},
+        publishedAt: fakeTimestamp,
+        updatedAt: fakeTimestamp,
+        createdAt: fakeTimestamp,
+      };
+      vi.mocked(getDoc).mockResolvedValue(
+        mockDocSnapshot('post-abc', raw) as Awaited<ReturnType<typeof getDoc>>,
+      );
+
+      const result = await lastValueFrom(service.getPostById('post-abc'));
+
+      // normalizePost converts Firestore Timestamps to milliseconds
+      const expectedMs = fakeTimestamp.seconds * 1000;
+      expect(result).toMatchObject({
+        id: 'post-abc',
+        slug: 'hello',
+        title: 'Hello World',
+        status: 'draft',
+        publishedAt: expectedMs,
+        updatedAt: expectedMs,
+        createdAt: expectedMs,
+      });
+    });
+
+    it('throws an error when the document does not exist', async () => {
+      vi.mocked(getDoc).mockResolvedValue(
+        mockDocSnapshot('missing', null) as Awaited<ReturnType<typeof getDoc>>,
+      );
+
+      await expect(lastValueFrom(service.getPostById('missing'))).rejects.toThrow(
+        'Post not found: missing',
+      );
+    });
+  });
+
+  // -------------------------------------------------------------------------
+  describe('getAllPosts', () => {
+    it('returns all posts mapped from the snapshot', async () => {
+      const post1 = makeBlogPost({ id: 'a', title: 'Post A' });
+      const post2 = makeBlogPost({ id: 'b', title: 'Post B' });
+      const { id: _1, ...data1 } = post1;
+      const { id: _2, ...data2 } = post2;
+
+      vi.mocked(getDocs).mockResolvedValue(
+        mockQuerySnapshot([
+          { id: 'a', data: data1 as unknown as Record<string, unknown> },
+          { id: 'b', data: data2 as unknown as Record<string, unknown> },
+        ]) as Awaited<ReturnType<typeof getDocs>>,
+      );
+
+      const result = await lastValueFrom(service.getAllPosts());
+
+      expect(result).toHaveLength(2);
+      expect(result[0].id).toBe('a');
+      expect(result[1].id).toBe('b');
+    });
+
+    it('passes orderBy("updatedAt", "desc") to query', async () => {
+      vi.mocked(getDocs).mockResolvedValue(
+        mockQuerySnapshot([]) as Awaited<ReturnType<typeof getDocs>>,
+      );
+
+      await lastValueFrom(service.getAllPosts());
+
+      expect(vi.mocked(orderBy)).toHaveBeenCalledWith('updatedAt', 'desc');
+    });
+
+    it('returns an empty array when the collection is empty', async () => {
+      vi.mocked(getDocs).mockResolvedValue(
+        mockQuerySnapshot([]) as Awaited<ReturnType<typeof getDocs>>,
+      );
+
+      const result = await lastValueFrom(service.getAllPosts());
+
+      expect(result).toEqual([]);
+    });
+  });
+
+  // -------------------------------------------------------------------------
+  describe('savePost — new post (id === "")', () => {
+    it('calls setDoc with the generated id and returns the post with that id', async () => {
+      const newPost = makeBlogPost({ id: '' });
+      vi.mocked(setDoc).mockResolvedValue(undefined);
+
+      const result = await lastValueFrom(service.savePost(newPost));
+
+      expect(vi.mocked(setDoc)).toHaveBeenCalledTimes(1);
+      expect(vi.mocked(updateDoc)).not.toHaveBeenCalled();
+      expect(result.id).toBe('generated-xyz');
+    });
+
+    it('stores the id field inside the document payload', async () => {
+      const newPost = makeBlogPost({ id: '' });
+      vi.mocked(setDoc).mockResolvedValue(undefined);
+
+      await lastValueFrom(service.savePost(newPost));
+
+      expect(vi.mocked(setDoc)).toHaveBeenCalledWith(
+        expect.anything(),
+        expect.objectContaining({ id: 'generated-xyz' }),
+      );
+    });
+
+    it('stamps createdAt and updatedAt as numeric milliseconds', async () => {
+      const newPost = makeBlogPost({ id: '' });
+      vi.mocked(setDoc).mockResolvedValue(undefined);
+
+      const result = await lastValueFrom(service.savePost(newPost));
+
+      expect(typeof result.createdAt).toBe('number');
+      expect(typeof result.updatedAt).toBe('number');
+    });
+  });
+
+  // -------------------------------------------------------------------------
+  describe('savePost — existing post (id !== "")', () => {
+    it('calls updateDoc and returns the post with updated updatedAt', async () => {
+      const existingPost = makeBlogPost({ id: 'post-existing' });
+      vi.mocked(updateDoc).mockResolvedValue(undefined);
+
+      const result = await lastValueFrom(service.savePost(existingPost));
+
+      expect(vi.mocked(updateDoc)).toHaveBeenCalledTimes(1);
+      expect(vi.mocked(updateDoc)).toHaveBeenCalledWith(
+        expect.anything(),
+        expect.objectContaining({ updatedAt: fakeTimestamp }),
+      );
+      expect(vi.mocked(setDoc)).not.toHaveBeenCalled();
+      expect(result.id).toBe('post-existing');
+      expect(typeof result.updatedAt).toBe('number');
+    });
+  });
+
+  // -------------------------------------------------------------------------
+  describe('Timestamp.now mock', () => {
+    it('does not call the real Firebase SDK', () => {
+      expect(vi.mocked(Timestamp.now)).toBeDefined();
+    });
+  });
+
+  // -------------------------------------------------------------------------
+  describe('deleteStorageFile', () => {
+    it('calls ref() with the storage instance and the given path', async () => {
+      vi.mocked(deleteObject).mockResolvedValue(undefined);
+
+      await lastValueFrom(service.deleteStorageFile('posts/p1/cover/img.jpg'));
+
+      expect(vi.mocked(ref)).toHaveBeenCalledWith(
+        expect.anything(),
+        'posts/p1/cover/img.jpg',
+      );
+    });
+
+    it('calls deleteObject with the ref returned by ref()', async () => {
+      const fakeRef = { _path: 'posts/p1/cover/img.jpg' };
+      vi.mocked(ref).mockReturnValue(fakeRef as unknown as ReturnType<typeof ref>);
+      vi.mocked(deleteObject).mockResolvedValue(undefined);
+
+      await lastValueFrom(service.deleteStorageFile('posts/p1/cover/img.jpg'));
+
+      expect(vi.mocked(deleteObject)).toHaveBeenCalledWith(fakeRef);
+    });
+
+    it('returns an Observable that resolves to void when deleteObject succeeds', async () => {
+      vi.mocked(deleteObject).mockResolvedValue(undefined);
+
+      const result = await lastValueFrom(service.deleteStorageFile('any/path'));
+
+      expect(result).toBeUndefined();
+    });
+  });
+});

package/src/lib/services/post.service.ts

@@ -0,0 +1,148 @@
+import { inject, Injectable } from '@angular/core';
+import {
+  collection,
+  doc,
+  getDoc,
+  getDocs,
+  limit,
+  orderBy,
+  query,
+  setDoc,
+  Timestamp,
+  updateDoc,
+  where,
+} from 'firebase/firestore';
+import { deleteObject, ref } from 'firebase/storage';
+import { from, Observable, of } from 'rxjs';
+import { catchError, map } from 'rxjs/operators';
+import { FIREBASE_STORAGE, FIRESTORE } from '../firebase/firebase.config';
+import type { BlogPost } from '../models/post.model';
+import { normalizePost } from '../utils/normalize-post';
+import type { IBlogPostService } from '../tokens/post-service.token';
+
+@Injectable({ providedIn: 'root' })
+export class PostService implements IBlogPostService {
+  // Non-null assertions are safe: PostService is only active in the browser
+  // where FIRESTORE and FIREBASE_STORAGE are always initialized.
+  // On the server, BLOG_POST_SERVICE resolves to ServerBlogPostService instead.
+  private readonly firestore = inject(FIRESTORE)!;
+  private readonly storage = inject(FIREBASE_STORAGE)!;
+
+  getPublishedPosts(): Observable<BlogPost[]> {
+    const q = query(
+      collection(this.firestore, 'posts'),
+      where('status', '==', 'published'),
+      orderBy('publishedAt', 'desc'),
+    );
+    return from(getDocs(q)).pipe(
+      map((snapshot) =>
+        snapshot.docs.map((d) => normalizePost({ id: d.id, ...d.data() })),
+      ),
+      catchError((err) => {
+        console.error('[PostService.getPublishedPosts]', err);
+        return of([]);
+      }),
+    );
+  }
+
+  getPostBySlug(slug: string): Observable<BlogPost | null> {
+    const q = query(
+      collection(this.firestore, 'posts'),
+      where('status', '==', 'published'),
+      where('slug', '==', slug),
+      limit(1),
+    );
+    return from(getDocs(q)).pipe(
+      map((snapshot) => {
+        if (snapshot.empty) return null;
+        const d = snapshot.docs[0];
+        return normalizePost({ id: d.id, ...d.data() });
+      }),
+      catchError((err) => {
+        console.error('[PostService.getPostBySlug]', err);
+        return of(null);
+      }),
+    );
+  }
+
+  getPostsByTag(tag: string): Observable<BlogPost[]> {
+    const q = query(
+      collection(this.firestore, 'posts'),
+      where('status', '==', 'published'),
+      where('tags', 'array-contains', tag),
+      orderBy('publishedAt', 'desc'),
+    );
+    return from(getDocs(q)).pipe(
+      map((snapshot) =>
+        snapshot.docs.map((d) => normalizePost({ id: d.id, ...d.data() })),
+      ),
+      catchError((err) => {
+        console.error('[PostService.getPostsByTag]', err);
+        return of([]);
+      }),
+    );
+  }
+
+  getAllPosts(): Observable<BlogPost[]> {
+    const q = query(
+      collection(this.firestore, 'posts'),
+      orderBy('updatedAt', 'desc'),
+    );
+    return from(getDocs(q)).pipe(
+      map((snapshot) =>
+        snapshot.docs.map((d) => normalizePost({ id: d.id, ...d.data() })),
+      ),
+      catchError((err) => {
+        console.error('[PostService.getAllPosts]', err);
+        return of([]);
+      }),
+    );
+  }
+
+  getPostById(id: string): Observable<BlogPost> {
+    return from(getDoc(doc(this.firestore, 'posts', id))).pipe(
+      map((snapshot) => {
+        if (!snapshot.exists()) throw new Error(`Post not found: ${id}`);
+        return normalizePost({ id: snapshot.id, ...snapshot.data() });
+      }),
+    );
+  }
+
+  deleteStorageFile(storagePath: string): Observable<void> {
+    const fileRef = ref(this.storage, storagePath);
+    return from(deleteObject(fileRef));
+  }
+
+  savePost(post: BlogPost): Observable<BlogPost> {
+    const nowMs = Date.now();
+    const nowTs = Timestamp.fromMillis(nowMs);
+
+    if (post.id === '') {
+      const newId = doc(collection(this.firestore, 'posts')).id;
+      const savedPost: BlogPost = { ...post, id: newId, createdAt: nowMs, updatedAt: nowMs };
+      // Write Timestamp objects to Firestore for proper ordering/querying
+      const firestorePayload = { ...savedPost, createdAt: nowTs, updatedAt: nowTs };
+      return from(
+        setDoc(doc(this.firestore, 'posts', newId), firestorePayload),
+      ).pipe(
+        map(() => savedPost),
+        catchError((err) => {
+          console.error('[PostService.savePost/create]', err);
+          throw err;
+        }),
+      );
+    }
+
+    const savedPost: BlogPost = { ...post, updatedAt: nowMs };
+    const firestorePayload = { ...savedPost, updatedAt: nowTs };
+    return from(
+      updateDoc(doc(this.firestore, 'posts', post.id), firestorePayload),
+    ).pipe(
+      map(() => savedPost),
+      catchError((err) => {
+        console.error('[PostService.savePost/update]', err);
+        throw err;
+      }),
+    );
+  }
+}

package/src/lib/services/site-config.service.ts

@@ -0,0 +1,86 @@
+import { inject, Injectable, makeStateKey } from '@angular/core';
+import { doc, getDoc, setDoc, Timestamp } from 'firebase/firestore';
+import { defer, from, Observable, of } from 'rxjs';
+import { catchError, filter, map } from 'rxjs/operators';
+import { FIRESTORE } from '../firebase/firebase.config';
+import type { AboutPageConfig, SiteConfig } from '../models/site-config.model';
+import { normalizeSiteConfig } from '../utils/normalize-site-config';
+import type { ISiteConfigService } from '../tokens/site-config-service.token';
+
+export const ABOUT_CONFIG_TRANSFER_KEY = makeStateKey<AboutPageConfig | null>('about-config');
+
+function stripUndefined(obj: Record<string, unknown>): Record<string, unknown> {
+  const result: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(obj)) {
+    if (value === undefined) continue;
+    if (value !== null && typeof value === 'object' && !Array.isArray(value) && value.constructor === Object) {
+      result[key] = stripUndefined(value as Record<string, unknown>);
+    } else {
+      result[key] = value;
+    }
+  }
+  return result;
+}
+
+@Injectable({ providedIn: 'root' })
+export class SiteConfigService implements ISiteConfigService {
+  private readonly firestore = inject(FIRESTORE);
+
+  getSiteConfig(siteId: string): Observable<SiteConfig | null> {
+    if (!this.firestore) return of(null);
+    const ref = doc(this.firestore, 'site-config', siteId);
+    return from(getDoc(ref)).pipe(
+      map((snap) => {
+        if (!snap.exists()) return null;
+        return normalizeSiteConfig({ id: snap.id, ...snap.data() });
+      }),
+      catchError((err) => {
+        console.error('[SiteConfigService.getSiteConfig]', err);
+        return of(null);
+      }),
+    );
+  }
+
+  getDefaultSiteConfig(): Observable<SiteConfig | null> {
+    return this.getSiteConfig('default');
+  }
+
+  /** Returns the default SiteConfig, filtering out null (no-document) results. */
+  getConfig(): Observable<SiteConfig> {
+    return this.getDefaultSiteConfig().pipe(
+      filter((c): c is SiteConfig => c !== null),
+    );
+  }
+
+  /**
+   * Convenience method that maps the default SiteConfig to its pages.about field.
+   * Does not make a separate Firestore read.
+   * TransferState hydration is handled by the aboutPageResolver in the blog app.
+   */
+  getAboutConfig(): Observable<AboutPageConfig | null> {
+    return this.getConfig().pipe(
+      map((c) => c.pages?.about ?? null),
+    );
+  }
+
+  saveSiteConfig(config: SiteConfig): Observable<SiteConfig> {
+    if (!this.firestore) return of(config);
+    const siteId = config.id || 'default';
+    const nowMs = Date.now();
+    const nowTs = Timestamp.fromMillis(nowMs);
+    const saved: SiteConfig = { ...config, id: siteId, updatedAt: nowMs };
+    const firestorePayload = stripUndefined({
+      ...saved,
+      updatedAt: nowTs,
+    } as unknown as Record<string, unknown>);
+    return defer(() =>
+      setDoc(doc(this.firestore!, 'site-config', siteId), firestorePayload),
+    ).pipe(
+      map(() => saved),
+      catchError((err) => {
+        console.error('[SiteConfigService.saveSiteConfig]', err);
+        throw err;
+      }),
+    );
+  }
+}

package/src/lib/services/tag.service.ts

@@ -0,0 +1,24 @@
+import { inject, Injectable } from '@angular/core';
+import { collection, getDocs } from 'firebase/firestore';
+import { from, Observable, of } from 'rxjs';
+import { catchError, map } from 'rxjs/operators';
+import { FIRESTORE } from '../firebase/firebase.config';
+import type { Tag } from '../models/tag.model';
+
+@Injectable({ providedIn: 'root' })
+export class TagService {
+  private readonly firestore = inject(FIRESTORE);
+
+  getAllTags(): Observable<Tag[]> {
+    if (!this.firestore) return of([]);
+    return from(getDocs(collection(this.firestore, 'tags'))).pipe(
+      map((snapshot) =>
+        snapshot.docs.map((doc) => ({ id: doc.id, ...doc.data() }) as Tag),
+      ),
+      catchError((err) => {
+        console.error('[TagService.getAllTags]', err);
+        return of([]);
+      }),
+    );
+  }
+}

package/src/lib/tokens/post-service.token.ts

@@ -0,0 +1,14 @@
+import { InjectionToken, makeStateKey } from '@angular/core';
+import type { Observable } from 'rxjs';
+import type { BlogPost } from '../models/post.model';
+
+export interface IBlogPostService {
+  getPublishedPosts(): Observable<BlogPost[]>;
+  getPostBySlug(slug: string): Observable<BlogPost | null>;
+}
+
+export const BLOG_POST_SERVICE = new InjectionToken<IBlogPostService>(
+  'BLOG_POST_SERVICE',
+);
+
+export const POSTS_TRANSFER_KEY = makeStateKey<BlogPost[]>('blog-posts');

package/src/lib/tokens/site-config-service.token.ts

@@ -0,0 +1,12 @@
+import { InjectionToken } from '@angular/core';
+import type { Observable } from 'rxjs';
+import type { AboutPageConfig, SiteConfig } from '../models/site-config.model';
+
+export interface ISiteConfigService {
+  getAboutConfig(): Observable<AboutPageConfig | null>;
+  getConfig(): Observable<SiteConfig>;
+}
+
+export const SITE_CONFIG_SERVICE = new InjectionToken<ISiteConfigService>(
+  'SITE_CONFIG_SERVICE',
+);

package/src/lib/utils/normalize-author.ts

@@ -0,0 +1,50 @@
+import type { Author } from '../models/author.model';
+import type { SocialLink, SocialPlatform } from '../models/site-config.model';
+
+function normalizeTimestamp(value: unknown): number {
+  if (value == null) return 0;
+  if (typeof value === 'number') return value;
+  if (value instanceof Date) return value.getTime();
+  if (typeof value === 'object') {
+    const v = value as Record<string, unknown>;
+    if (typeof (v as { toMillis?: unknown }).toMillis === 'function') {
+      return (v as { toMillis(): number }).toMillis();
+    }
+    if (typeof (v as { toDate?: unknown }).toDate === 'function') {
+      return (v as { toDate(): Date }).toDate().getTime();
+    }
+    if (typeof v['_seconds'] === 'number') {
+      return (v['_seconds'] as number) * 1000 +
+        Math.floor(((v['_nanoseconds'] as number) ?? 0) / 1e6);
+    }
+    if (typeof v['seconds'] === 'number') {
+      return (v['seconds'] as number) * 1000 +
+        Math.floor(((v['nanoseconds'] as number) ?? 0) / 1e6);
+    }
+  }
+  return 0;
+}
+
+function normalizeSocialLinks(raw: unknown): SocialLink[] | undefined {
+  if (!Array.isArray(raw)) return undefined;
+  return (raw as Record<string, unknown>[]).map((item) => ({
+    platform: item['platform'] as SocialPlatform,
+    url: (item['url'] as string) ?? '',
+    label: item['label'] as string | undefined,
+    icon: item['icon'] as string | undefined,
+  }));
+}
+
+export function normalizeAuthor(raw: Record<string, unknown>): Author {
+  return {
+    id: (raw['id'] as string) ?? '',
+    displayName: (raw['displayName'] as string) ?? '',
+    bio: raw['bio'] as string | undefined,
+    photoUrl: raw['photoUrl'] as string | undefined,
+    photoUrlDark: raw['photoUrlDark'] as string | undefined,
+    socialLinks: normalizeSocialLinks(raw['socialLinks']),
+    email: raw['email'] as string | undefined,
+    createdAt: normalizeTimestamp(raw['createdAt']),
+    updatedAt: normalizeTimestamp(raw['updatedAt']),
+  };
+}

package/src/lib/utils/normalize-post.ts

@@ -0,0 +1,66 @@
+import type { BlogPost } from '../models/post.model';
+
+/**
+ * Converts a Firestore timestamp in any of its runtime forms to milliseconds.
+ *
+ * Handles:
+ *  - Native Timestamp objects from either SDK (have .toMillis())
+ *  - Objects with .toDate() method (client SDK Timestamp without .toMillis())
+ *  - Admin SDK serialized form { _seconds, _nanoseconds }
+ *  - Plain { seconds, nanoseconds } objects
+ *  - Already-numeric millisecond values
+ *  - JavaScript Date objects
+ */
+function normalizeTimestamp(value: unknown): number {
+  if (value == null) return 0;
+  if (typeof value === 'number') return value;
+  if (value instanceof Date) return value.getTime();
+  if (typeof value === 'object') {
+    const v = value as Record<string, unknown>;
+    if (typeof (v as { toMillis?: unknown }).toMillis === 'function') {
+      return (v as { toMillis(): number }).toMillis();
+    }
+    if (typeof (v as { toDate?: unknown }).toDate === 'function') {
+      return (v as { toDate(): Date }).toDate().getTime();
+    }
+    if (typeof v['_seconds'] === 'number') {
+      return (v['_seconds'] as number) * 1000 +
+        Math.floor(((v['_nanoseconds'] as number) ?? 0) / 1e6);
+    }
+    if (typeof v['seconds'] === 'number') {
+      return (v['seconds'] as number) * 1000 +
+        Math.floor(((v['nanoseconds'] as number) ?? 0) / 1e6);
+    }
+  }
+  return 0;
+}
+
+/**
+ * Maps raw Firestore DocumentData (merged with its doc id) into a fully typed,
+ * TransferState-serializable BlogPost. Callers must pass { id: doc.id, ...doc.data() }.
+ */
+export function normalizePost(raw: Record<string, unknown>): BlogPost {
+  return {
+    id: (raw['id'] as string) ?? '',
+    slug: (raw['slug'] as string) ?? '',
+    title: (raw['title'] as string) ?? '',
+    subtitle: raw['subtitle'] as string | undefined,
+    status: raw['status'] as BlogPost['status'],
+    content: (raw['content'] as string) ?? '',
+    excerpt: raw['excerpt'] as string | undefined,
+    thumbnailUrl: raw['thumbnailUrl'] as string | undefined,
+    thumbnailAlt: raw['thumbnailAlt'] as string | undefined,
+    tags: (raw['tags'] as string[]) ?? [],
+    authorId: raw['authorId'] as string | undefined,
+    readingTimeMinutes: raw['readingTimeMinutes'] as number | undefined,
+    embeddedMedia: (raw['embeddedMedia'] as BlogPost['embeddedMedia']) ?? {},
+    seo: (raw['seo'] as BlogPost['seo']) ?? {},
+    publishedAt: normalizeTimestamp(raw['publishedAt']),
+    scheduledPublishAt:
+      raw['scheduledPublishAt'] != null
+        ? normalizeTimestamp(raw['scheduledPublishAt'])
+        : undefined,
+    updatedAt: normalizeTimestamp(raw['updatedAt']),
+    createdAt: normalizeTimestamp(raw['createdAt']),
+  };
+}