@brightsideoy/kama 0.1.0-alpha.98 → 1.0.0-alpha.2

package/templates/astro-starter/src/lib/cms.ts

@@ -0,0 +1,197 @@
+// src/lib/cms.ts
+
+export interface TreeNode {
+    id: number;
+    treeNodeId: number;
+    parentId: number | null;
+    title: string;
+    slug: string;
+    path: string;
+    nodeType: string;
+    hidden?: number;
+    summary?: string;
+    url?: string;
+    target?: string;
+    children?: TreeNode[];
+    [key: string]: any;
+}
+
+export interface ContentBlock {
+    instanceId: number;
+    componentId: string;
+    data: Record<string, any>;
+    [key: string]: any;
+}
+
+export interface RegionMeta {
+    isInherited: boolean;
+    inheritedFromId?: string | number;
+    inheritedFromTitle?: string;
+    [key: string]: any;
+}
+
+export interface NodeResponse {
+    channelId: string | number;
+    treeId: string | number;
+    language: string;
+    node: {
+        id: number;
+        title: string;
+        slug: string;
+        nodeType: string;
+        path?: string;
+        createdAt?: string;
+        updatedAt?: string;
+        summary?: string;
+        children?: any[];
+        [key: string]: any;
+    };
+    content: Record<string, ContentBlock[]>;
+    regionMeta?: Record<string, RegionMeta>;
+    [key: string]: any;
+}
+
+export interface ChannelResponse {
+    id: number;
+    key: string;
+    label: string;
+    channelType: string;
+    defaultLanguage: string;
+    // Core branding & SEO properties typed for IDE auto-complete:
+    logo?: string;
+    logoText?: string;
+    favicon?: string;
+    siteTitle?: string;
+    titleSuffix?: string;
+    defaultSeoImage?: string;
+    // 🎯 Dynamically captures all public fields defined in YAML channel schemas:
+    [key: string]: any;
+}
+
+/**
+ * Resolves base CMS URL across runtime environments safely via Astro
+ */
+export function getCmsUrl(): string {
+    const url =
+        import.meta.env.PUBLIC_API_URL ||
+        import.meta.env.PUBLIC_CMS_URL ||
+        'http://localhost:8787';
+    return url.replace(/\/+$/, '');
+}
+
+/**
+ * Resolves Default Channel ID across environments
+ */
+export function getChannelId(): string {
+    return import.meta.env.PUBLIC_CHANNEL_ID || 'website';
+}
+
+/**
+ * Resolves Default Tree ID across environments
+ */
+export function getTreeId(): string {
+    return import.meta.env.PUBLIC_TREE_ID || 'navigation';
+}
+
+/**
+ * Fetch channel metadata by key/ID.
+ * Serves global site branding, logos, favicons, and schema-defined public fields.
+ */
+export async function getChannel(
+    channelKeyOrId: string = getChannelId(),
+    customFetch: typeof fetch = fetch
+): Promise<ChannelResponse | null> {
+    const baseUrl = getCmsUrl();
+    const requestUrl = `${baseUrl}/api/v1/channel/${channelKeyOrId}`;
+
+    try {
+        const res = await customFetch(requestUrl, {
+            headers: {
+                Accept: 'application/json',
+            },
+        });
+
+        if (!res.ok) return null;
+
+        return (await res.json()) as ChannelResponse;
+    } catch (err) {
+        console.error('[CMS Client] Failed to fetch public channel:', err);
+        return null;
+    }
+}
+
+/**
+ * Fetch tree navigation hierarchy by tree key/ID and channel.
+ * Supports passing Cloudflare Service Bindings (e.g. env.CMS_WORKER.fetch)
+ */
+export async function getTree(
+    treeKeyOrId: string = getTreeId(),
+    channel: string | number = getChannelId(),
+    customFetch: typeof fetch = fetch
+): Promise<TreeNode[]> {
+    const baseUrl = getCmsUrl();
+    const requestUrl = `${baseUrl}/api/v1/tree/${treeKeyOrId}?channelId=${channel}`;
+
+    try {
+        const res = await customFetch(requestUrl, {
+            headers: {
+                Accept: 'application/json',
+            },
+        });
+
+        if (!res.ok) return [];
+
+        const data = await res.json();
+        return data.items || [];
+    } catch (err) {
+        console.error('[CMS Client] Failed to fetch public tree:', err);
+        return [];
+    }
+}
+
+/**
+ * Fetch single content node payload by its full URL path.
+ * Supports passing Cloudflare Service Bindings (e.g. env.CMS_WORKER.fetch)
+ */
+export async function getNodeByPath(
+    path: string,
+    channel: string | number = getChannelId(),
+    preview = false,
+    customFetch: typeof fetch = fetch
+): Promise<NodeResponse | null> {
+    const cleanPath = path.replace(/^\/+|\/+$/g, '') || 'home';
+    const baseUrl = getCmsUrl();
+    const requestUrl = `${baseUrl}/api/v1/node/${cleanPath}?channelId=${channel}&preview=${preview}`;
+
+    try {
+        const res = await customFetch(requestUrl, {
+            headers: {
+                Accept: 'application/json',
+            },
+        });
+
+        if (!res.ok) return null;
+
+        return (await res.json()) as NodeResponse;
+    } catch (err) {
+        console.error('[CMS Client] Failed to fetch node by path:', err);
+        return null;
+    }
+}
+
+/**
+ * Resolves relative media URLs against base CMS URL
+ */
+export function getMediaUrl(url?: string): string {
+    if (!url) return '';
+
+    const baseUrl = getCmsUrl();
+    let cleanUrl = url.replace(/^http:\/\/localhost:\d+/, baseUrl);
+
+    if (cleanUrl.startsWith('http://') || cleanUrl.startsWith('https://')) {
+        return cleanUrl;
+    }
+
+    const cleanPath = cleanUrl.replace(/^\/+/, '');
+    return `${baseUrl}/${cleanPath}`;
+}

package/templates/astro-starter/src/lib/media/kama-image-service.ts

@@ -0,0 +1,56 @@
+// src/lib/media/kama-image-service.ts
+
+import type { LocalImageService } from "astro";
+
+/**
+ * Checks whether a given path or URL represents a vector SVG image.
+ */
+function isSvgImage(src: string): boolean {
+    if (!src) return false;
+    const lower = src.toLowerCase();
+    return lower.endsWith('.svg') || lower.includes('image/svg+xml') || lower.includes('.svg?');
+}
+
+const kamaImageService: LocalImageService = {
+    getURL(options) {
+        let src = options.src;
+
+        if (typeof src === 'object' && 'src' in src) {
+            src = src.src;
+        }
+
+        if (typeof src === 'string') {
+            try {
+                // 🎯 SVG Guard: Bypass raster query params for vector graphics
+                if (isSvgImage(src)) {
+                    return src;
+                }
+
+                const url = new URL(src, 'http://localhost');
+
+                if (options.width) url.searchParams.set('w', Math.round(options.width).toString());
+                if (options.height) url.searchParams.set('h', Math.round(options.height).toString());
+                if (options.quality) url.searchParams.set('q', options.quality.toString());
+                if (options.format) url.searchParams.set('f', options.format.toString());
+
+                return src.startsWith('http') ? url.toString() : (url.pathname + url.search);
+            } catch (e) {
+                return src;
+            }
+        }
+        return String(src);
+    },
+    parseURL(url) {
+        return { src: url.pathname + url.search };
+    },
+    getHTMLAttributes(options) {
+        return {
+            width: options.width,
+            height: options.height,
+            loading: options.loading || 'lazy',
+            decoding: options.decoding || 'async',
+        };
+    }
+};
+
+export default kamaImageService;

package/templates/astro-starter/src/lib/media/media-proxy.ts

@@ -0,0 +1,129 @@
+// src/lib/media/media-proxy.ts
+
+import type { APIContext } from "astro";
+
+export function getMimeType(filePath: string): string {
+    const ext = filePath.split(".").pop()?.toLowerCase();
+    switch (ext) {
+        case "jpg":
+        case "jpeg": return "image/jpeg";
+        case "png": return "image/png";
+        case "webp": return "image/webp";
+        case "avif": return "image/avif";
+        case "svg": return "image/svg+xml";
+        case "gif": return "image/gif";
+        case "pdf": return "application/pdf";
+        case "mp4": return "video/mp4";
+        case "webm": return "video/webm";
+        default: return "application/octet-stream";
+    }
+}
+
+export async function handleMediaProxy({ request, params, url, locals }: APIContext): Promise<Response> {
+    // 🎯 Safely extract Cloudflare context from Astro locals dual-environment
+    const runtime = locals.runtime || (locals as any).cfContext;
+    const workerEnv = runtime?.env || {};
+    const cfContext = runtime?.ctx || {};
+
+    // 🎯 Detect if Astro is requesting a resized variant
+    const hasResizeParams = url.searchParams.has('w') || url.searchParams.has('h') || url.searchParams.has('q') || url.searchParams.has('f');
+
+    // 1. Cloudflare Edge Cache API
+    let edgeCache: Cache | null = null;
+    try {
+        if (typeof caches !== "undefined" && caches.default) {
+            edgeCache = caches.default;
+            const cachedResponse = await edgeCache.match(request);
+            if (cachedResponse) return cachedResponse;
+        }
+    } catch (err) {
+        console.warn("[Media Proxy] Edge cache match failed:", err);
+    }
+
+    const rawPath = params.path || "";
+    const cleanPath = rawPath.replace(/^\/+|\/+$/g, "");
+
+    // 2. Direct R2 Lookup (ONLY IF NO RESIZING PARAMS ARE PRESENT AND WE ARE IN PROD)
+    const mediaBucket = workerEnv.MEDIA_BUCKET;
+    if (mediaBucket && cleanPath && !hasResizeParams) {
+        try {
+            let r2Object = await mediaBucket.get(cleanPath);
+            if (!r2Object) r2Object = await mediaBucket.get(cleanPath.startsWith("media/") ? cleanPath.replace(/^media\//, "") : `media/${cleanPath}`);
+
+            if (r2Object) {
+                if (request.headers.get("if-none-match") === r2Object.httpEtag) {
+                    return new Response(null, { status: 304 });
+                }
+
+                const headers = new Headers();
+                r2Object.writeHttpMetadata(headers);
+                headers.set("etag", r2Object.httpEtag);
+                headers.set("Cache-Control", "public, max-age=31536000, immutable");
+                headers.set("Access-Control-Allow-Origin", "*");
+                if (!headers.get("content-type") || headers.get("content-type") === "application/octet-stream") {
+                    headers.set("content-type", getMimeType(cleanPath));
+                }
+
+                const r2Response = new Response(r2Object.body, { status: 200, headers });
+
+                if (edgeCache) {
+                    const cachePromise = edgeCache.put(request, r2Response.clone());
+                    if (cfContext?.waitUntil) cfContext.waitUntil(cachePromise);
+                    else cachePromise.catch(e => console.warn(e));
+                }
+
+                return r2Response;
+            }
+        } catch (r2Err) {
+            console.warn("[Media Proxy] R2 lookup error:", r2Err);
+        }
+    }
+
+    // 3. Forward to Backend (Handles Local Sharp Resizing AND Cloudflare Images Resizing)
+    try {
+        let backendResponse: Response;
+
+        // A. Production Mode (Cloudflare Service Binding)
+        if (workerEnv.CMS_WORKER) {
+            backendResponse = await workerEnv.CMS_WORKER.fetch(request);
+        }
+        // B. Local Dev Mode (Standard HTTP Fetch to local Hono Server)
+        else {
+            const cmsUrl = import.meta.env.PUBLIC_CMS_URL || 'http://localhost:8787';
+            const targetUrl = `${cmsUrl}${url.pathname}${url.search}`;
+
+            // Forward request headers (like Accept for WebP/AVIF negotiation)
+            backendResponse = await fetch(targetUrl, {
+                headers: {
+                    'Accept': request.headers.get('Accept') || 'image/webp,image/avif,image/*,*/*;q=0.8'
+                }
+            });
+        }
+
+        if (backendResponse.ok) {
+            const newHeaders = new Headers(backendResponse.headers);
+            newHeaders.set("Cache-Control", "public, max-age=31536000, immutable");
+            newHeaders.set("Access-Control-Allow-Origin", "*");
+
+            const proxyResponse = new Response(backendResponse.body, {
+                status: backendResponse.status,
+                statusText: backendResponse.statusText,
+                headers: newHeaders,
+            });
+
+            if (edgeCache) {
+                const cachePromise = edgeCache.put(request, proxyResponse.clone());
+                if (cfContext?.waitUntil) cfContext.waitUntil(cachePromise);
+                else cachePromise.catch(e => console.warn(e));
+            }
+
+            return proxyResponse;
+        }
+
+        return backendResponse;
+    } catch (error) {
+        console.error("❌ Media Proxy Forwarding Error:", error);
+    }
+
+    return new Response("Not found", { status: 404 });
+}

package/templates/astro-starter/src/lib/media/media-url.ts

@@ -0,0 +1,98 @@
+// src/lib/media/media-url.ts
+
+export function toRelativeMediaPath(rawUrl: string): string {
+    if (!rawUrl) return "";
+
+    let clean = String(rawUrl);
+    clean = clean.replace(/^https?:\/\/[^/]+/, "");
+    clean = clean.split("?")[0].split("#")[0];
+
+    const mediaIndex = clean.indexOf("/media/");
+    if (mediaIndex !== -1) {
+        return `/media/${clean
+            .slice(mediaIndex + "/media/".length)
+            .replace(/^\/+/, "")}`;
+    }
+
+    return clean.startsWith("/") ? clean : `/${clean}`;
+}
+
+/**
+ * Checks whether a given path or MIME type represents a vector SVG image.
+ */
+export function isSvgImage(urlOrMime: string): boolean {
+    if (!urlOrMime) return false;
+    const lower = urlOrMime.toLowerCase();
+    return lower.endsWith('.svg') || lower.includes('image/svg+xml') || lower.includes('.svg?');
+}
+
+export function buildAgnosticImageUrl(
+    url: string,
+    width: number,
+    quality = 75,
+): string {
+    const cleanPath = toRelativeMediaPath(url);
+    if (!cleanPath) return "";
+
+    // 🎯 Vector Guard: Return pristine path for SVGs without width/quality query parameters
+    if (isSvgImage(cleanPath)) {
+        return cleanPath;
+    }
+
+    const urlObj = new URL(cleanPath, "http://localhost");
+    urlObj.searchParams.set("w", String(width));
+    urlObj.searchParams.set("q", String(quality));
+    urlObj.searchParams.set("f", "auto");
+
+    return urlObj.pathname + urlObj.search;
+}
+
+export interface GetImageUriOptions {
+    width?: number;
+    quality?: number;
+    fallback?: string;
+    absoluteOrigin?: string; // e.g. siteOrigin for OG/Twitter tags or JSON-LD
+}
+
+/**
+ * Universal CMS Image Helper
+ * Safely resolves strings, asset objects, and array-wrapped media into relative or absolute CSP-compliant URLs.
+ */
+export function getImageUri(
+    imgObj: any,
+    options: GetImageUriOptions = {}
+): string | null {
+    const { width, quality = 75, fallback = null, absoluteOrigin } = options;
+
+    if (!imgObj) return fallback;
+
+    // 1. Unpack arrays (e.g. favicon: [{ url: '/media/...' }])
+    const target = Array.isArray(imgObj) ? imgObj[0] : imgObj;
+    if (!target) return fallback;
+
+    // 2. Detect mimeType if present on asset object
+    const isSvgAsset = isSvgImage(target?.mimeType || "") || isSvgImage(target?.filename || "");
+
+    // 3. Extract raw URL path across standard CMS field variations
+    const rawPath =
+        typeof target === "string"
+            ? target
+            : target?.variants?.standard?.url || target?.url || target?.path || null;
+
+    if (!rawPath) return fallback;
+
+    // 4. Process URL through buildAgnosticImageUrl (SVGs bypass raster params automatically)
+    let finalPath = (width && !isSvgAsset && !isSvgImage(rawPath))
+        ? buildAgnosticImageUrl(rawPath, width, quality)
+        : toRelativeMediaPath(rawPath);
+
+    if (!finalPath) return fallback;
+
+    // 5. Prepend absolute origin if requested (for Open Graph, Twitter cards, or JSON-LD)
+    if (absoluteOrigin) {
+        const cleanOrigin = absoluteOrigin.replace(/\/+$/, "");
+        return `${cleanOrigin}${finalPath.startsWith("/") ? "" : "/"}${finalPath}`;
+    }
+
+    return finalPath;
+}