@foliokit/cms-core 1.0.0 → 1.0.1

package/README.md

@@ -1,3 +1,63 @@
 # @foliokit/cms-core
-Part of the [Folio](https://github.com/doug-williamson/foliokit) ecosystem.
-> This package is in early development. API is unstable.
+
+Core Firebase services, data models, and injection tokens for the FolioKit CMS.
+Provides `provideFolioKit()` — the single-call bootstrapper that sets up Firebase
+(Firestore, Storage, Auth) and default service bindings for Angular applications.
+
+Part of the [FolioKit](https://github.com/doug-williamson/foliokit) ecosystem.
+
+## Install
+
+```bash
+npm install @foliokit/cms-core
+```
+
+## Peer Dependencies
+
+| Package | Version |
+|---------|---------|
+| `@angular/common` | `^21.2.4` |
+| `@angular/core` | `^21.2.4` |
+| `firebase` | `^11.10.0` |
+| `rxjs` | `~7.8.0` |
+
+## Quick Start
+
+```typescript
+// app.config.ts
+import { provideFolioKit } from '@foliokit/cms-core';
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    provideFolioKit({
+      firebaseConfig: {
+        apiKey: '...',
+        authDomain: '...',
+        projectId: '...',
+        storageBucket: '...',
+        messagingSenderId: '...',
+        appId: '...',
+      },
+    }),
+  ],
+};
+```
+
+`provideFolioKit()` registers:
+- Firebase App, Firestore, Storage, and Auth (SSR-safe — returns `null` on the server)
+- `PostService` bound to `BLOG_POST_SERVICE`
+- `SiteConfigService` bound to `SITE_CONFIG_SERVICE`
+- Optional `SITE_ID` token (when `siteId` is provided)
+
+## What's Included
+
+- **`provideFolioKit(config)`** — single-call bootstrapper
+- **`provideFirebase(options, useEmulator)`** — lower-level Firebase-only setup
+- **Data models** — `BlogPost`, `SiteConfig`, `NavItem`, `Author`, `Tag`, `SeoMeta`, `AboutPageConfig`, `LinksPageConfig`, `HomePageConfig`
+- **Services** — `PostService`, `SiteConfigService`, `AuthorService`, `AuthService`, `TagService`
+- **DI tokens** — `BLOG_POST_SERVICE`, `SITE_CONFIG_SERVICE`, `SITE_ID`, `FIREBASE_OPTIONS`, `FIRESTORE`, `FIREBASE_STORAGE`, `FIREBASE_AUTH`
+- **Pipes** — `TagLabelPipe`
+
+## Full Documentation
+
+[foliokitcms.com/docs/getting-started](https://foliokitcms.com/docs/getting-started)

package/eslint.config.mjs

@@ -0,0 +1,48 @@
+import nx from '@nx/eslint-plugin';
+import baseConfig from '../../eslint.config.mjs';
+
+export default [
+  ...baseConfig,
+  {
+    files: ['**/*.json'],
+    rules: {
+      '@nx/dependency-checks': [
+        'error',
+        {
+          ignoredFiles: ['{projectRoot}/eslint.config.{js,cjs,mjs,ts,cts,mts}'],
+        },
+      ],
+    },
+    languageOptions: {
+      parser: await import('jsonc-eslint-parser'),
+    },
+  },
+  ...nx.configs['flat/angular'],
+  ...nx.configs['flat/angular-template'],
+  {
+    files: ['**/*.ts'],
+    rules: {
+      '@angular-eslint/directive-selector': [
+        'error',
+        {
+          type: 'attribute',
+          prefix: 'lib',
+          style: 'camelCase',
+        },
+      ],
+      '@angular-eslint/component-selector': [
+        'error',
+        {
+          type: 'element',
+          prefix: 'lib',
+          style: 'kebab-case',
+        },
+      ],
+    },
+  },
+  {
+    files: ['**/*.html'],
+    // Override or add rules here
+    rules: {},
+  },
+];

package/ng-package.json

@@ -0,0 +1,7 @@
+{
+  "$schema": "../../node_modules/ng-packagr/ng-package.schema.json",
+  "dest": "../../dist/libs/cms-core",
+  "lib": {
+    "entryFile": "src/index.ts"
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foliokit/cms-core",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Core Firebase services, models, and tokens for FolioKit CMS",
   "keywords": [
     "angular",
@@ -12,7 +12,7 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/dougwilliamson/foliokit"
+    "url": "git+https://github.com/dougwilliamson/foliokit.git"
   },
   "publishConfig": {
     "access": "public"
@@ -20,22 +20,9 @@
   "peerDependencies": {
     "@angular/common": "^21.2.4",
     "@angular/core": "^21.2.4",
+    "@angular/router": "^21.2.4",
     "firebase": "^11.10.0",
     "rxjs": "~7.8.0"
   },
-  "sideEffects": false,
-  "module": "esm2022/foliokit-cms-core.js",
-  "typings": "foliokit-cms-core.d.ts",
-  "exports": {
-    "./package.json": {
-      "default": "./package.json"
-    },
-    ".": {
-      "types": "./foliokit-cms-core.d.ts",
-      "default": "./esm2022/foliokit-cms-core.js"
-    }
-  },
-  "dependencies": {
-    "tslib": "^2.3.0"
-  }
-}
+  "sideEffects": false
+}

package/project.json

@@ -0,0 +1,32 @@
+{
+  "name": "cms-core",
+  "$schema": "../../node_modules/nx/schemas/project-schema.json",
+  "sourceRoot": "libs/cms-core/src",
+  "prefix": "lib",
+  "projectType": "library",
+  "tags": [],
+  "targets": {
+    "build": {
+      "executor": "@nx/angular:ng-packagr-lite",
+      "outputs": ["{workspaceRoot}/dist/{projectRoot}"],
+      "options": {
+        "project": "libs/cms-core/ng-package.json",
+        "tsConfig": "libs/cms-core/tsconfig.lib.json"
+      },
+      "configurations": {
+        "production": {
+          "tsConfig": "libs/cms-core/tsconfig.lib.prod.json"
+        },
+        "development": {}
+      },
+      "defaultConfiguration": "production"
+    },
+    "test": {
+      "executor": "@nx/angular:unit-test",
+      "options": {}
+    },
+    "lint": {
+      "executor": "@nx/eslint:lint"
+    }
+  }
+}

package/{esm2022/index.js → src/index.ts}

@@ -1,5 +1,6 @@
 export * from './lib/firebase/firebase.config';
 export * from './lib/firebase/firebase.providers';
+export * from './lib/firebase/foliokit.providers';
 // firebase-admin.ts is intentionally excluded — server-only, import directly in SSR server files
 export * from './lib/models/post.model';
 export * from './lib/models/site-config.model';
@@ -7,10 +8,15 @@ export * from './lib/models/page.model';
 export * from './lib/models/tag.model';
 export * from './lib/models/author.model';
 export * from './lib/services/auth.service';
+export * from './lib/services/author.service';
 export * from './lib/services/post.service';
-export * from './lib/services/page.service';
 export * from './lib/services/site-config.service';
 export * from './lib/services/tag.service';
 export * from './lib/tokens/post-service.token';
-export * from './lib/tokens/page-service.token';
-//# sourceMappingURL=index.js.map
+export * from './lib/tokens/site-config-service.token';
+export * from './lib/pipes/tag-label.pipe';
+
+// ── Resolvers ─────────────────────────────────────────────────────────────────
+export * from './lib/resolvers/about-page.resolver';
+export * from './lib/resolvers/links-page.resolver';
+export * from './lib/resolvers/posts.resolver';

package/src/lib/cms-core/cms-core.html

@@ -0,0 +1 @@
+<p>CmsCore works!</p>

package/src/lib/cms-core/cms-core.spec.ts

@@ -0,0 +1,44 @@
+import { TestBed } from '@angular/core/testing';
+import { ADMIN_EMAIL, SITE_ID, provideFolioKit } from '@foliokit/cms-core';
+
+// Minimal Firebase config for testing — no real project needed; these tests
+// never establish a network connection.
+const testFirebaseConfig = {
+  apiKey: 'test-key',
+  authDomain: 'test.firebaseapp.com',
+  projectId: 'test-project',
+  storageBucket: 'test-project.appspot.com',
+  messagingSenderId: '000000000000',
+  appId: '1:000000000000:web:000000000000',
+};
+
+describe('cms-core public API smoke tests', () => {
+  afterEach(() => TestBed.resetTestingModule());
+
+  it('provideFolioKit() returns a truthy EnvironmentProviders object', () => {
+    const result = provideFolioKit({ firebaseConfig: testFirebaseConfig });
+    expect(result).toBeTruthy();
+  });
+
+  it('ADMIN_EMAIL token is injectable when provided', () => {
+    TestBed.configureTestingModule({
+      providers: [{ provide: ADMIN_EMAIL, useValue: 'admin@example.com' }],
+    });
+    const email = TestBed.inject(ADMIN_EMAIL);
+    expect(email).toBe('admin@example.com');
+  });
+
+  it('SITE_ID token is optionally injectable — returns null when absent', () => {
+    TestBed.configureTestingModule({ providers: [] });
+    const siteId = TestBed.inject(SITE_ID, null);
+    expect(siteId).toBeNull();
+  });
+
+  it('SITE_ID token is injectable when provided', () => {
+    TestBed.configureTestingModule({
+      providers: [{ provide: SITE_ID, useValue: 'my-site' }],
+    });
+    const siteId = TestBed.inject(SITE_ID);
+    expect(siteId).toBe('my-site');
+  });
+});

package/src/lib/cms-core/cms-core.ts

@@ -0,0 +1,9 @@
+import { Component } from '@angular/core';
+
+@Component({
+  selector: 'lib-cms-core',
+  imports: [],
+  templateUrl: './cms-core.html',
+  styleUrl: './cms-core.scss',
+})
+export class CmsCore {}

package/src/lib/firebase/firebase-admin.ts

@@ -0,0 +1,32 @@
+/**
+ * Firebase Admin SDK initializer — Node.js only.
+ *
+ * Credential resolution order:
+ *   1. If GOOGLE_APPLICATION_CREDENTIALS contains a JSON object (Firebase App
+ *      Hosting injects secret values as raw strings, not file paths), parse it
+ *      directly with admin.credential.cert().
+ *   2. Otherwise fall back to Application Default Credentials (ADC), which
+ *      covers local dev (file-path env var) and Cloud Run managed SA.
+ *
+ * Never import this module in browser bundles. Import directly in SSR server
+ * entry files (e.g. apps/blog/src/server.ts) — it is intentionally excluded
+ * from the @foliokit/cms-core barrel export.
+ */
+import admin from 'firebase-admin';
+
+export function initAdminApp(): admin.app.App {
+  if (!admin.apps.length) {
+    const credEnv = process.env['GOOGLE_APPLICATION_CREDENTIALS'];
+    const credential = credEnv?.trimStart().startsWith('{')
+      ? admin.credential.cert(
+          JSON.parse(credEnv) as admin.ServiceAccount,
+        )
+      : admin.credential.applicationDefault();
+
+    admin.initializeApp({
+      credential,
+      projectId: process.env['FIREBASE_PROJECT_ID'],
+    });
+  }
+  return admin.app();
+}

package/src/lib/firebase/firebase.config.ts

@@ -0,0 +1,26 @@
+import { InjectionToken } from '@angular/core';
+import type { FirebaseApp, FirebaseOptions } from 'firebase/app';
+import type { Firestore } from 'firebase/firestore';
+import type { FirebaseStorage } from 'firebase/storage';
+import type { Auth } from 'firebase/auth';
+
+export const FIREBASE_OPTIONS = new InjectionToken<FirebaseOptions>('FIREBASE_OPTIONS');
+export const FIREBASE_APP = new InjectionToken<FirebaseApp>('FIREBASE_APP');
+export const FIRESTORE = new InjectionToken<Firestore | null>('FIRESTORE');
+export const FIREBASE_STORAGE = new InjectionToken<FirebaseStorage | null>('FIREBASE_STORAGE');
+export const FIREBASE_AUTH = new InjectionToken<Auth | null>('FIREBASE_AUTH');
+/**
+ * The email address that identifies the admin user.
+ *
+ * Injected by `provideAdminKit({ adminEmail })` and read by
+ * `AuthService.isAdmin()` to gate all write operations.
+ *
+ * **Must match all four authorization surfaces:**
+ * 1. The Firebase Authentication account (Google sign-in email)
+ * 2. The `adminEmail` passed to `provideAdminKit()` in `app.config.ts`
+ * 3. The `isAdmin()` function in `firestore.rules`
+ * 4. The author document created by the seed script
+ *
+ * @see {@link https://github.com/dougwilliamson/foliokit/blob/main/docs/security/admin-authorization.md}
+ */
+export const ADMIN_EMAIL = new InjectionToken<string>('ADMIN_EMAIL');

package/src/lib/firebase/firebase.providers.ts

@@ -0,0 +1,89 @@
+import {
+  EnvironmentProviders,
+  PLATFORM_ID,
+  inject,
+  makeEnvironmentProviders,
+} from '@angular/core';
+import { isPlatformBrowser } from '@angular/common';
+import { FirebaseOptions, getApp, getApps, initializeApp } from 'firebase/app';
+import {
+  connectFirestoreEmulator,
+  getFirestore,
+  initializeFirestore,
+  memoryLocalCache,
+} from 'firebase/firestore';
+import { connectStorageEmulator, getStorage } from 'firebase/storage';
+import { connectAuthEmulator, getAuth } from 'firebase/auth';
+import {
+  FIREBASE_APP,
+  FIREBASE_AUTH,
+  FIREBASE_OPTIONS,
+  FIREBASE_STORAGE,
+  FIRESTORE,
+} from './firebase.config';
+
+export function provideFirebase(
+  options: FirebaseOptions,
+  useEmulator = false
+): EnvironmentProviders {
+  return makeEnvironmentProviders([
+    {
+      provide: FIREBASE_OPTIONS,
+      useValue: options,
+    },
+    {
+      // Firebase app is a Node.js-process-level singleton. In SSR, each request
+      // creates a new DI context but shares the same global Firebase registry, so
+      // we must reuse the existing app rather than calling initializeApp again.
+      provide: FIREBASE_APP,
+      useFactory: () =>
+        getApps().length ? getApp() : initializeApp(inject(FIREBASE_OPTIONS)),
+    },
+    {
+      // Same singleton constraint applies to the Firestore instance.
+      // initializeFirestore throws if called a second time for the same app, so
+      // fall back to getFirestore() which returns the already-configured instance.
+      // Client SDK must not run on the server — Admin SDK handles SSR reads.
+      provide: FIRESTORE,
+      useFactory: () => {
+        const platformId = inject(PLATFORM_ID);
+        if (!isPlatformBrowser(platformId)) return null;
+        const app = inject(FIREBASE_APP);
+        try {
+          const db = initializeFirestore(app, { localCache: memoryLocalCache(), ignoreUndefinedProperties: true });
+          if (useEmulator) {
+            connectFirestoreEmulator(db, '127.0.0.1', 8080);
+          }
+          return db;
+        } catch {
+          return getFirestore(app);
+        }
+      },
+    },
+    {
+      provide: FIREBASE_STORAGE,
+      useFactory: () => {
+        const platformId = inject(PLATFORM_ID);
+        if (!isPlatformBrowser(platformId)) return null;
+        const storage = getStorage(inject(FIREBASE_APP));
+        if (useEmulator) {
+          connectStorageEmulator(storage, '127.0.0.1', 9199);
+        }
+        return storage;
+      },
+    },
+    {
+      // Auth relies on browser APIs (IndexedDB, localStorage) — null on server
+      provide: FIREBASE_AUTH,
+      useFactory: () => {
+        const platformId = inject(PLATFORM_ID);
+        if (!isPlatformBrowser(platformId)) return null;
+        const auth = getAuth(inject(FIREBASE_APP));
+        if (useEmulator) {
+          connectAuthEmulator(auth, 'http://127.0.0.1:9099', { disableWarnings: true });
+        }
+        return auth;
+      },
+    },
+  ]);
+}

package/src/lib/firebase/foliokit.providers.ts

@@ -0,0 +1,178 @@
+import {
+  APP_INITIALIZER,
+  EnvironmentProviders,
+  InjectionToken,
+  PLATFORM_ID,
+  inject,
+  makeEnvironmentProviders,
+} from '@angular/core';
+import { isPlatformBrowser } from '@angular/common';
+import type { FirebaseOptions } from 'firebase/app';
+import { provideFirebase } from './firebase.providers';
+import { FIREBASE_AUTH } from './firebase.config';
+import { PostService } from '../services/post.service';
+import { SiteConfigService } from '../services/site-config.service';
+import { BLOG_POST_SERVICE } from '../tokens/post-service.token';
+import { SITE_CONFIG_SERVICE } from '../tokens/site-config-service.token';
+
+/**
+ * Injection token for the current site identifier.
+ *
+ * **Provided by {@link provideFolioKit}** when `siteId` is set in the config.
+ * Consumers should inject this token to read the active site ID — do not
+ * provide it yourself unless you are bypassing `provideFolioKit()`.
+ *
+ * Useful for multi-site deployments where a single Firebase project
+ * serves several distinct sites. Services like `SiteConfigService` can
+ * use this to scope Firestore reads to a specific site document.
+ *
+ * @example
+ * ```ts
+ * // In any component or service — reads the value set by provideFolioKit():
+ * readonly siteId = inject(SITE_ID, { optional: true });
+ *
+ * loadConfig() {
+ *   const id = this.siteId ?? 'default';
+ *   return this.siteConfigService.getSiteConfig(id);
+ * }
+ * ```
+ */
+export const SITE_ID = new InjectionToken<string>('SITE_ID');
+
+/**
+ * Configuration object accepted by {@link provideFolioKit}.
+ */
+export interface FolioKitConfig {
+  /**
+   * Firebase project credentials. Obtain from the Firebase Console under
+   * Project Settings → Your apps → SDK setup and configuration.
+   *
+   * @example
+   * ```ts
+   * firebaseConfig: {
+   *   apiKey: 'AIza...',
+   *   authDomain: 'my-project.firebaseapp.com',
+   *   projectId: 'my-project',
+   *   storageBucket: 'my-project.appspot.com',
+   *   messagingSenderId: '1234567890',
+   *   appId: '1:1234567890:web:abc123',
+   * }
+   * ```
+   */
+  firebaseConfig: FirebaseOptions;
+
+  /**
+   * Optional site identifier for multi-site deployments.
+   *
+   * When provided, the value is registered as the {@link SITE_ID} injection
+   * token so that services and components can vary behaviour per site without
+   * requiring separate Firebase projects.
+   */
+  siteId?: string;
+
+  /**
+   * Optional Firebase Authentication tenant ID.
+   *
+   * When provided, `auth.tenantId` is set on the Auth instance during app
+   * initialisation via `APP_INITIALIZER`. Required for Google Cloud Identity
+   * Platform multi-tenant projects. Has no effect in SSR contexts where Auth
+   * is null.
+   *
+   * @see https://firebase.google.com/docs/auth/web/multi-tenancy
+   */
+  tenantId?: string;
+
+  /**
+   * When `true`, all Firebase services connect to the local emulator suite
+   * instead of production endpoints:
+   * - Firestore → `127.0.0.1:8080`
+   * - Storage   → `127.0.0.1:9199`
+   * - Auth      → `http://127.0.0.1:9099`
+   *
+   * @default false
+   */
+  useEmulator?: boolean;
+}
+
+/**
+ * Bootstrap FolioKit in a single call.
+ *
+ * Registers all Firebase services (app, Firestore, Storage, Auth), binds the
+ * default {@link PostService} and {@link SiteConfigService} implementations to
+ * their public tokens, and optionally stores `siteId` / `tenantId` config.
+ *
+ * Use this instead of `provideFirebase()` unless you need custom service
+ * implementations — in which case call `provideFirebase()` directly and
+ * provide your own service aliases.
+ *
+ * **Overriding the default service bindings**
+ *
+ * The last provider wins in Angular's DI system. Add your own binding *after*
+ * `provideFolioKit()` in the providers array to override the defaults:
+ *
+ * ```ts
+ * providers: [
+ *   provideFolioKit({ firebaseConfig: environment.firebase }),
+ *   { provide: BLOG_POST_SERVICE, useExisting: MyCustomPostService },
+ * ]
+ * ```
+ *
+ * @param config - FolioKit configuration including Firebase credentials and
+ *   optional site/tenant identifiers.
+ * @returns An `EnvironmentProviders` token suitable for use in
+ *   `ApplicationConfig.providers` or `bootstrapApplication`.
+ *
+ * @example
+ * ```ts
+ * // app.config.ts
+ * export const appConfig: ApplicationConfig = {
+ *   providers: [
+ *     provideRouter(routes),
+ *     provideAnimationsAsync(),
+ *     provideHttpClient(withFetch()),
+ *     provideMarkdown(),
+ *     provideFolioKit({
+ *       firebaseConfig: environment.firebase,
+ *       useEmulator: environment.useEmulator,
+ *     }),
+ *   ],
+ * };
+ * ```
+ */
+export function provideFolioKit(config: FolioKitConfig): EnvironmentProviders {
+  const providers: Parameters<typeof makeEnvironmentProviders>[0] = [
+    // Firebase services: app, Firestore, Storage, Auth (SSR-safe).
+    provideFirebase(config.firebaseConfig, config.useEmulator ?? false),
+
+    // Default concrete service implementations bound to their public tokens.
+    // Override by re-providing the token after this call in the same array.
+    { provide: BLOG_POST_SERVICE, useExisting: PostService },
+    { provide: SITE_CONFIG_SERVICE, useExisting: SiteConfigService },
+  ];
+
+  // Optionally expose siteId as an injectable constant.
+  if (config.siteId !== undefined) {
+    providers.push({ provide: SITE_ID, useValue: config.siteId });
+  }
+
+  // Optionally apply a Firebase Auth tenant ID for multi-tenant projects.
+  // Uses APP_INITIALIZER to run after the Auth instance is created.
+  if (config.tenantId !== undefined) {
+    const tenantId = config.tenantId;
+    providers.push({
+      provide: APP_INITIALIZER,
+      useFactory: () => {
+        const platformId = inject(PLATFORM_ID);
+        const auth = inject(FIREBASE_AUTH);
+        return () => {
+          if (isPlatformBrowser(platformId) && auth) {
+            auth.tenantId = tenantId;
+          }
+        };
+      },
+      multi: true,
+    });
+  }
+
+  return makeEnvironmentProviders(providers);
+}

package/src/lib/models/author.model.ts

@@ -0,0 +1,16 @@
+import type { SocialLink } from './site-config.model';
+
+export interface Author {
+  id: string;
+  displayName: string;
+  bio?: string;
+  photoUrl?: string;
+  /** Firebase Storage URL — shown in dark mode when set */
+  photoUrlDark?: string;
+  socialLinks?: SocialLink[];
+  email?: string;
+  /** Unix milliseconds. */
+  createdAt: number;
+  /** Unix milliseconds. */
+  updatedAt: number;
+}

package/src/lib/models/page.model.ts

@@ -0,0 +1,11 @@
+import type { SocialPlatform } from './site-config.model';
+
+export interface LinksLink {
+  id: string;
+  label: string;
+  url: string;
+  icon?: string;
+  platform?: SocialPlatform;
+  highlighted?: boolean;
+  order: number;
+}

package/src/lib/models/post.model.ts

@@ -0,0 +1,41 @@
+export interface SeoMeta {
+  title?: string;
+  description?: string;
+  keywords?: string[];
+  ogImage?: string;
+  canonicalUrl?: string;
+  noIndex?: boolean;
+}
+
+export interface EmbeddedMediaEntry {
+  token: string;
+  storagePath: string;
+  downloadUrl: string;
+  alt: string;
+  mimeType: string;
+}
+
+export interface BlogPost {
+  id: string;
+  slug: string;
+  title: string;
+  subtitle?: string;
+  status: 'published' | 'draft' | 'scheduled' | 'archived';
+  content: string;
+  excerpt?: string;
+  thumbnailUrl?: string;
+  thumbnailAlt?: string;
+  tags: string[];
+  authorId?: string;
+  readingTimeMinutes?: number;
+  embeddedMedia: Record<string, EmbeddedMediaEntry>;
+  seo: SeoMeta;
+  /** Unix milliseconds. Stored as Firestore Timestamp but always normalized on read. */
+  publishedAt: number;
+  /** Unix milliseconds, optional. */
+  scheduledPublishAt?: number;
+  /** Unix milliseconds. */
+  updatedAt: number;
+  /** Unix milliseconds. */
+  createdAt: number;
+}