@astronox/core 0.2.3 → 0.3.0

package/README.md

@@ -13,7 +13,9 @@ in the consuming site.
 npm install @astronox/core
 ```
 
-Astro is a peer dependency. Consumers must use a compatible Astro 7 release.
+Astro is a peer dependency. Firebase is an optional peer dependency used only
+by the dedicated Firebase entry points. Consumers must install the providers
+they activate.
 
 ## Usage
 
@@ -52,3 +54,16 @@ and responsive media presentation are available through the `i18n`, `routing`,
 definitions, translations, route names, product metadata, and assets. Generic
 component labels can extend `defaultCoreMessages` through
 `resolveCoreMessages()` while retaining the English fallback.
+
+## Infrastructure
+
+- [`content`](docs/content-markdown.md): reusable ordered content and Markdown
+  contracts.
+- [`Firebase admin`](docs/integrations/firebase-admin.md): authentication,
+  claims, Firestore, and app-owned mappings.
+- [`R2 publication`](docs/integrations/r2-publication.md): full provider
+  snapshots and build-time public projection.
+- [`AdSense`](docs/integrations/adsense.md): provider setup, consent, slots, and
+  fallback canvas.
+- [`release workflow`](docs/release-workflow.md): local links, verification, and
+  consumer pinning order.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astronox/core",
-  "version": "0.2.3",
+  "version": "0.3.0",
   "description": "Reusable Astro components, patterns, styles, and infrastructure for AstroNox sites.",
   "license": "MIT",
   "keywords": [
@@ -29,6 +29,8 @@
   ],
   "exports": {
     ".": "./src/index.ts",
+    "./ads": "./src/ads/index.ts",
+    "./ads/adsense": "./src/ads/adsense/index.ts",
     "./client": "./src/client/index.ts",
     "./admin": "./src/admin/index.ts",
     "./auth": "./src/auth/index.ts",
@@ -37,12 +39,14 @@
     "./components": "./src/components/index.ts",
     "./composition": "./src/composition/index.ts",
     "./config": "./src/config/index.ts",
+    "./content": "./src/content/index.ts",
     "./data": "./src/data/index.ts",
     "./data/firestore/client": "./src/data/firestore/client/index.ts",
     "./display": "./src/display/index.ts",
     "./i18n": "./src/i18n/index.ts",
     "./layouts": "./src/layouts/index.ts",
     "./patterns": "./src/patterns/index.ts",
+    "./publication": "./src/publication/index.ts",
     "./primitives": "./src/primitives/index.ts",
     "./routing": "./src/routing/index.ts",
     "./seo": "./src/seo/index.ts",
@@ -54,7 +58,9 @@
     "check": "astro check",
     "format": "prettier --write .",
     "format:check": "prettier --check .",
-    "lint": "eslint ."
+    "lint": "eslint .",
+    "test": "node --import tsx --test test/*.test.ts",
+    "verify": "npm run format:check && npm run lint && npm run check && npm test && npm pack --dry-run"
   },
   "publishConfig": {
     "access": "public"
@@ -64,10 +70,16 @@
     "url": "git+https://github.com/gaudesp/astronox-core.git"
   },
   "peerDependencies": {
-    "astro": "^7.0.0"
+    "astro": "^7.0.0",
+    "firebase": "^12.0.0"
+  },
+  "peerDependenciesMeta": {
+    "firebase": {
+      "optional": true
+    }
   },
   "dependencies": {
-    "firebase": "^12.0.0",
+    "mdast-util-from-markdown": "2.0.2",
     "zod": "4.4.3"
   },
   "devDependencies": {
@@ -77,8 +89,10 @@
     "astro-eslint-parser": "1.4.0",
     "eslint": "9.39.5",
     "eslint-plugin-astro": "1.7.0",
+    "firebase": "^12.0.0",
     "prettier": "3.9.5",
     "prettier-plugin-astro": "0.14.1",
+    "tsx": "4.21.0",
     "typescript": "6.0.3",
     "typescript-eslint": "8.64.0"
   }

package/src/admin/authController.ts

@@ -0,0 +1,166 @@
+import { AuthorizationError, type AuthActor } from '../auth';
+import type { AdminStorage } from './cache';
+
+export type AdminAuthState =
+  | { status: 'pending' }
+  | { status: 'signed-out' }
+  | { status: 'denied' }
+  | { status: 'authenticated'; actor: AuthActor };
+
+export type AdminAuthSnapshot =
+  { status: 'authenticated'; actor: AuthActor } | { status: 'signed-out' };
+
+export type AdminAuthSnapshotStore = {
+  read(): AdminAuthSnapshot | null;
+  write(snapshot: AdminAuthSnapshot): void;
+};
+
+export type ClientAuthProvider = {
+  observe(
+    listener: (actor: AuthActor | null) => void,
+    onError?: (reason: unknown) => void,
+  ): () => void;
+  signIn(): Promise<AuthActor>;
+  signOut(): Promise<void>;
+};
+
+export function createAdminAuthController({
+  auth,
+  clearActorState,
+  isAuthorized,
+  snapshots,
+}: {
+  auth: ClientAuthProvider;
+  clearActorState(actorId: string): void;
+  isAuthorized(actor: AuthActor): boolean;
+  snapshots: AdminAuthSnapshotStore;
+}) {
+  type Listener = (state: AdminAuthState) => void;
+
+  const listeners = new Set<Listener>();
+  let state: AdminAuthState = snapshots.read() ?? { status: 'pending' };
+  let observing = false;
+
+  const setState = (next: AdminAuthState): void => {
+    state = next;
+    snapshots.write(
+      next.status === 'authenticated' ? next : { status: 'signed-out' },
+    );
+    listeners.forEach((listener) => listener(state));
+  };
+
+  const observeProvider = (): void => {
+    if (observing) return;
+    observing = true;
+    auth.observe(
+      (actor) => {
+        if (!actor) {
+          if (state.status !== 'denied') setState({ status: 'signed-out' });
+          return;
+        }
+        if (!isAuthorized(actor)) {
+          setState({ status: 'denied' });
+          void auth.signOut().catch((reason) => {
+            console.error(
+              '[admin] Failed to sign out a denied account',
+              reason,
+            );
+          });
+          return;
+        }
+        setState({ status: 'authenticated', actor });
+      },
+      (reason) => {
+        console.error('[admin] Failed to observe authentication', reason);
+        if (state.status === 'pending') setState({ status: 'signed-out' });
+      },
+    );
+  };
+
+  return {
+    getActor(): AuthActor | null {
+      return state.status === 'authenticated' ? state.actor : null;
+    },
+    observe(listener: Listener): () => void {
+      listeners.add(listener);
+      listener(state);
+      observeProvider();
+      return () => listeners.delete(listener);
+    },
+    requireActor(): AuthActor {
+      if (state.status === 'authenticated') return state.actor;
+      throw new AuthorizationError();
+    },
+    async signIn(): Promise<AuthActor> {
+      const actor = await auth.signIn();
+      if (!isAuthorized(actor)) {
+        setState({ status: 'denied' });
+        await auth.signOut().catch(() => undefined);
+        throw new AuthorizationError();
+      }
+      setState({ status: 'authenticated', actor });
+      return actor;
+    },
+    async signOut(): Promise<void> {
+      if (state.status === 'authenticated') clearActorState(state.actor.id);
+      await auth.signOut();
+      setState({ status: 'signed-out' });
+    },
+  } as const;
+}
+
+export function createBrowserAdminAuthSnapshotStore({
+  key,
+  storage,
+}: {
+  key: string;
+  storage?: AdminStorage;
+}): AdminAuthSnapshotStore {
+  const getStorage = (): AdminStorage => storage ?? localStorage;
+
+  return {
+    read() {
+      try {
+        const raw = getStorage().getItem(key);
+        if (!raw) return null;
+        const value: unknown = JSON.parse(raw);
+        if (!value || typeof value !== 'object') return null;
+        const snapshot = value as Partial<AdminAuthSnapshot>;
+        if (snapshot.status === 'signed-out') return { status: 'signed-out' };
+        if (snapshot.status !== 'authenticated') return null;
+        const actor = parseAuthActor(snapshot.actor);
+        return actor ? { status: 'authenticated', actor } : null;
+      } catch {
+        return null;
+      }
+    },
+    write(snapshot) {
+      try {
+        getStorage().setItem(key, JSON.stringify(snapshot));
+      } catch {
+        // Persistence is optional; Firebase remains authoritative.
+      }
+    },
+  };
+}
+
+function parseAuthActor(value: unknown): AuthActor | null {
+  if (!value || typeof value !== 'object') return null;
+  const actor = value as Partial<AuthActor>;
+  if (typeof actor.id !== 'string') return null;
+  const claims =
+    actor.claims &&
+    typeof actor.claims === 'object' &&
+    !Array.isArray(actor.claims)
+      ? actor.claims
+      : {};
+
+  return {
+    claims,
+    displayName:
+      typeof actor.displayName === 'string' ? actor.displayName : undefined,
+    email: typeof actor.email === 'string' ? actor.email : undefined,
+    id: actor.id,
+    imageUrl: typeof actor.imageUrl === 'string' ? actor.imageUrl : undefined,
+  };
+}

package/src/admin/cache.ts

@@ -11,9 +11,32 @@ export type AdminResourceCacheConfig<TItem, TStored> = {
   getKey(item: TItem): string;
   serializer: AdminResourceCacheSerializer<TItem, TStored>;
   sort(items: readonly TItem[]): TItem[];
+  storage?: AdminStorage;
   ttlMs?: number;
 };
 
+export type AdminStorage = Pick<
+  Storage,
+  'getItem' | 'key' | 'length' | 'removeItem' | 'setItem'
+>;
+
+export type AdminResourceCache<TItem> = {
+  append(actorId: string, page: AdminPage<TItem>): void;
+  clear(actorId: string): void;
+  editorKey: string;
+  find(actorId: string, id: string): TItem | null;
+  isLocalCursor(cursor?: string): boolean;
+  read(
+    actorId: string,
+    input?: { cursor?: string; limit?: number },
+  ): AdminPage<TItem> | null;
+  readEditor(actorId: string, id: string): TItem | null;
+  remove(actorId: string, id: string): void;
+  upsert(actorId: string, item: TItem): void;
+  write(actorId: string, page: AdminPage<TItem>): void;
+  writeEditor(actorId: string, item: TItem): boolean;
+};
+
 type StoredPage<TStored> = {
   expiresAt: number;
   items: TStored[];
@@ -34,8 +57,10 @@ export function createAdminResourceCache<TItem, TStored>({
   getKey,
   serializer,
   sort,
+  storage,
   ttlMs = 10 * 60 * 1000,
-}: AdminResourceCacheConfig<TItem, TStored>) {
+}: AdminResourceCacheConfig<TItem, TStored>): AdminResourceCache<TItem> {
+  const getStorage = (): AdminStorage => storage ?? sessionStorage;
   const collectionCacheKey = (actorId: string) =>
     `${collectionKey}:${encodeURIComponent(actorId)}`;
   const editorCacheKey = (id: string) =>
@@ -44,7 +69,8 @@ export function createAdminResourceCache<TItem, TStored>({
   const readSnapshot = (actorId: string): AdminPage<TItem> | null => {
     try {
       const key = collectionCacheKey(actorId);
-      const raw = sessionStorage.getItem(key);
+      const target = getStorage();
+      const raw = target.getItem(key);
       if (!raw) return null;
       const stored = JSON.parse(raw) as Partial<StoredPage<TStored>>;
       if (
@@ -52,7 +78,7 @@ export function createAdminResourceCache<TItem, TStored>({
         stored.expiresAt <= Date.now() ||
         !Array.isArray(stored.items)
       ) {
-        sessionStorage.removeItem(key);
+        target.removeItem(key);
         return null;
       }
 
@@ -60,7 +86,7 @@ export function createAdminResourceCache<TItem, TStored>({
       for (const value of stored.items) {
         const item = serializer.parse(value);
         if (!item) {
-          sessionStorage.removeItem(key);
+          target.removeItem(key);
           return null;
         }
         items.push(item);
@@ -83,7 +109,7 @@ export function createAdminResourceCache<TItem, TStored>({
         items: sort(page.items).map(serializer.serialize),
         nextCursor: page.nextCursor,
       };
-      sessionStorage.setItem(
+      getStorage().setItem(
         collectionCacheKey(actorId),
         JSON.stringify(payload),
       );
@@ -122,14 +148,14 @@ export function createAdminResourceCache<TItem, TStored>({
     },
     find(actorId: string, id: string): TItem | null {
       return (
-        readSnapshot(actorId)?.items.find((item) => getKey(item) === id) ??
-        null
+        readSnapshot(actorId)?.items.find((item) => getKey(item) === id) ?? null
       );
     },
     readEditor(actorId: string, id: string): TItem | null {
       try {
         const key = editorCacheKey(id);
-        const raw = sessionStorage.getItem(key);
+        const target = getStorage();
+        const raw = target.getItem(key);
         if (!raw) return null;
         const stored = JSON.parse(raw) as Partial<StoredEditor<TStored>>;
         if (
@@ -137,7 +163,7 @@ export function createAdminResourceCache<TItem, TStored>({
           typeof stored.expiresAt !== 'number' ||
           stored.expiresAt <= Date.now()
         ) {
-          sessionStorage.removeItem(key);
+          target.removeItem(key);
           return null;
         }
         return serializer.parse(stored.item);
@@ -177,7 +203,7 @@ export function createAdminResourceCache<TItem, TStored>({
         });
       }
       try {
-        sessionStorage.removeItem(editorCacheKey(id));
+        getStorage().removeItem(editorCacheKey(id));
       } catch {
         // Cleanup is best effort.
       }
@@ -189,7 +215,7 @@ export function createAdminResourceCache<TItem, TStored>({
           expiresAt: Date.now() + ttlMs,
           item: serializer.serialize(item),
         };
-        sessionStorage.setItem(
+        getStorage().setItem(
           editorCacheKey(getKey(item)),
           JSON.stringify(payload),
         );
@@ -200,18 +226,19 @@ export function createAdminResourceCache<TItem, TStored>({
     },
     clear(actorId: string): void {
       try {
-        sessionStorage.removeItem(collectionCacheKey(actorId));
-        for (let index = sessionStorage.length - 1; index >= 0; index -= 1) {
-          const key = sessionStorage.key(index);
+        const target = getStorage();
+        target.removeItem(collectionCacheKey(actorId));
+        for (let index = target.length - 1; index >= 0; index -= 1) {
+          const key = target.key(index);
           if (!key?.startsWith(`${editorKey}:`)) continue;
-          const raw = sessionStorage.getItem(key);
+          const raw = target.getItem(key);
           if (!raw) continue;
           const stored = JSON.parse(raw) as Partial<StoredEditor<TStored>>;
-          if (stored.actorId === actorId) sessionStorage.removeItem(key);
+          if (stored.actorId === actorId) target.removeItem(key);
         }
       } catch {
         // Cleanup is best effort.
       }
     },
-  } as const;
+  };
 }

package/src/admin/index.ts

@@ -1,3 +1,6 @@
+export * from './authController';
 export * from './contracts';
 export * from './cache';
 export * from './module';
+export * from './preparedDestination';
+export * from './resourceClient';

package/src/admin/preparedDestination.ts

@@ -0,0 +1,114 @@
+import type { AdminStorage } from './cache';
+
+type PreparedDestinationEnvelope<TStored> = {
+  actorId: string;
+  destination: string;
+  expiresAt: number;
+  payload: TStored;
+};
+
+export type PreparedDestinationCodec<TPayload, TStored> = {
+  parse(value: unknown): TPayload | null;
+  serialize(payload: TPayload): TStored;
+};
+
+export function normalizePreparedDestinationPath(pathname: string): string {
+  return pathname === '/' ? pathname : pathname.replace(/\/+$/, '');
+}
+
+export function createPreparedDestinationStore<TPayload, TStored>({
+  codec,
+  getActorId,
+  getBaseUrl,
+  keyPrefix,
+  storage,
+  ttlMs = 10 * 60 * 1000,
+}: {
+  codec: PreparedDestinationCodec<TPayload, TStored>;
+  getActorId(): string | null;
+  getBaseUrl?: () => string;
+  keyPrefix: string;
+  storage?: AdminStorage;
+  ttlMs?: number;
+}) {
+  const getStorage = (): AdminStorage => storage ?? sessionStorage;
+  const resolveBaseUrl = (): string => getBaseUrl?.() ?? window.location.href;
+  const getDestination = (href: string): string => {
+    const url = new URL(href, resolveBaseUrl());
+    return `${normalizePreparedDestinationPath(url.pathname)}${url.search}`;
+  };
+  const getKey = (href: string): string =>
+    `${keyPrefix}:${encodeURIComponent(getDestination(href))}`;
+
+  return {
+    clear(actorId?: string): void {
+      try {
+        const target = getStorage();
+        for (let index = target.length - 1; index >= 0; index -= 1) {
+          const key = target.key(index);
+          if (!key?.startsWith(`${keyPrefix}:`)) continue;
+          if (!actorId) {
+            target.removeItem(key);
+            continue;
+          }
+          const raw = target.getItem(key);
+          const envelope = raw
+            ? (JSON.parse(raw) as Partial<PreparedDestinationEnvelope<TStored>>)
+            : null;
+          if (envelope?.actorId === actorId) target.removeItem(key);
+        }
+      } catch {
+        // Prepared state is an optimization and must never block administration.
+      }
+    },
+    getKey,
+    read(href: string): TPayload | null {
+      try {
+        const actorId = getActorId();
+        if (!actorId) return null;
+        const key = getKey(href);
+        const target = getStorage();
+        const raw = target.getItem(key);
+        if (!raw) return null;
+        const envelope = JSON.parse(raw) as Partial<
+          PreparedDestinationEnvelope<TStored>
+        >;
+        if (
+          envelope.actorId !== actorId ||
+          envelope.destination !== getDestination(href) ||
+          typeof envelope.expiresAt !== 'number' ||
+          envelope.expiresAt <= Date.now()
+        ) {
+          target.removeItem(key);
+          return null;
+        }
+        const payload = codec.parse(envelope.payload);
+        if (!payload) target.removeItem(key);
+        return payload;
+      } catch {
+        return null;
+      }
+    },
+    remove(href: string): void {
+      try {
+        getStorage().removeItem(getKey(href));
+      } catch {
+        // Prepared state is an optimization and must never block administration.
+      }
+    },
+    write(actorId: string, href: string, payload: TPayload): void {
+      try {
+        const destination = getDestination(href);
+        const envelope: PreparedDestinationEnvelope<TStored> = {
+          actorId,
+          destination,
+          expiresAt: Date.now() + ttlMs,
+          payload: codec.serialize(payload),
+        };
+        getStorage().setItem(getKey(href), JSON.stringify(envelope));
+      } catch {
+        // Prepared state is an optimization and must never block administration.
+      }
+    },
+  } as const;
+}

package/src/admin/resourceClient.ts

@@ -0,0 +1,107 @@
+import type { AuthActor } from '../auth';
+import type { AdminResourceCache } from './cache';
+import type { AdminResource } from './contracts';
+
+type IndexInput = { cursor?: string; limit?: number } | undefined;
+
+export function createCachedAdminResourceClient<
+  TItem,
+  TCreateInput,
+  TUpdateInput = TCreateInput,
+>({
+  afterDelete,
+  afterWrite,
+  cache,
+  getActor,
+  resource,
+}: {
+  afterDelete?(actorId: string, id: string): void;
+  afterWrite?(actorId: string, item: TItem): void;
+  cache: AdminResourceCache<TItem>;
+  getActor(): AuthActor;
+  resource: AdminResource<TItem, TCreateInput, TUpdateInput, IndexInput>;
+}) {
+  const indexRequests = new Map<string, ReturnType<typeof resource.getIndex>>();
+  const detailRequests = new Map<
+    string,
+    ReturnType<typeof resource.getDetail>
+  >();
+
+  const requestKey = (actorId: string, input?: IndexInput): string =>
+    `${actorId}:${input?.cursor ?? 'root'}:${input?.limit ?? 25}`;
+
+  const syncWrite =
+    afterWrite ?? ((actorId, item) => cache.upsert(actorId, item));
+  const syncDelete =
+    afterDelete ?? ((actorId, id) => cache.remove(actorId, id));
+  const isActiveActor = (actorId: string): boolean => {
+    try {
+      return getActor().id === actorId;
+    } catch {
+      return false;
+    }
+  };
+
+  return {
+    getIndex(input?: IndexInput) {
+      const actor = getActor();
+      const cached = cache.read(actor.id, input);
+      if (cached) return Promise.resolve(cached);
+      const requestInput = cache.isLocalCursor(input?.cursor)
+        ? { ...input, cursor: undefined }
+        : input;
+      const key = requestKey(actor.id, requestInput);
+      const pending = indexRequests.get(key);
+      if (pending) return pending;
+
+      const request = resource.getIndex(requestInput).then((page) => {
+        if (isActiveActor(actor.id)) {
+          if (requestInput?.cursor) {
+            cache.append(actor.id, page);
+          } else {
+            cache.write(actor.id, page);
+          }
+        }
+        return page;
+      });
+      indexRequests.set(key, request);
+      void request.then(
+        () => indexRequests.delete(key),
+        () => indexRequests.delete(key),
+      );
+      return request;
+    },
+    getDetail(id: string) {
+      const actor = getActor();
+      const cached = cache.find(actor.id, id);
+      if (cached) return Promise.resolve(cached);
+      const key = `${actor.id}:${id}`;
+      const pending = detailRequests.get(key);
+      if (pending) return pending;
+      const request = resource.getDetail({ id });
+      detailRequests.set(key, request);
+      void request.then(
+        () => detailRequests.delete(key),
+        () => detailRequests.delete(key),
+      );
+      return request;
+    },
+    async create(input: TCreateInput) {
+      const actor = getActor();
+      const item = await resource.create(input, actor);
+      if (isActiveActor(actor.id)) syncWrite(actor.id, item);
+      return item;
+    },
+    async update(id: string, input: TUpdateInput) {
+      const actor = getActor();
+      const item = await resource.update({ id, value: input }, actor);
+      if (isActiveActor(actor.id)) syncWrite(actor.id, item);
+      return item;
+    },
+    async delete(id: string) {
+      const actor = getActor();
+      await resource.delete({ id }, actor);
+      if (isActiveActor(actor.id)) syncDelete(actor.id, id);
+    },
+  } as const;
+}

package/src/ads/adsense/index.ts

@@ -0,0 +1 @@
+export * from '../adsense';