ayezee-astro-cms 1.0.0 → 1.1.0

package/dist/cloudinary-utils.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Cloudinary URL helpers for optimized image delivery
+ *
+ * Upload presets store originals at full quality with NO transformations.
+ * Transformations are applied dynamically via URL at delivery time.
+ *
+ * Presets in Cloudinary dashboard:
+ * - ayezee_gallery: For gallery/fan-wall images → folder: gallery-images
+ * - ayezee_optimized: For project logos → folder: project-logos
+ */
+type CloudinaryTransformOptions = {
+    width?: number;
+    height?: number;
+    quality?: number | "auto" | "auto:best" | "auto:good" | "auto:eco" | "auto:low";
+    format?: "auto" | "webp" | "avif" | "jpg" | "png";
+    crop?: "fill" | "fit" | "limit" | "scale" | "thumb" | "pad";
+    gravity?: "auto" | "face" | "center" | "north" | "south" | "east" | "west";
+    dpr?: number | "auto";
+    aspectRatio?: string;
+};
+/**
+ * Build a Cloudinary URL with transformations
+ */
+export declare function buildCloudinaryUrl(url: string, options?: CloudinaryTransformOptions): string;
+/**
+ * Generate srcset for responsive images
+ */
+export declare function buildCloudinarySrcSet(url: string, widths: number[], quality?: CloudinaryTransformOptions["quality"]): string;
+/**
+ * Preset configurations for common use cases
+ */
+export declare const CLOUDINARY_PRESETS: {
+    readonly logo: {
+        readonly default: (url: string) => string;
+        readonly thumb: (url: string) => string;
+        readonly large: (url: string) => string;
+    };
+    readonly gallery: {
+        readonly src: (url: string) => string;
+        readonly srcset: (url: string) => string;
+        readonly hero: (url: string) => string;
+        readonly thumb: (url: string) => string;
+    };
+    readonly avatar: (url: string) => string;
+};
+/**
+ * Helper to check if a URL is from Cloudinary
+ */
+export declare function isCloudinaryUrl(url: string): boolean;
+/**
+ * Extract public ID from Cloudinary URL
+ */
+export declare function getCloudinaryPublicId(url: string): string | null;
+export {};

package/dist/cloudinary-utils.js

@@ -0,0 +1,152 @@
+/**
+ * Cloudinary URL helpers for optimized image delivery
+ *
+ * Upload presets store originals at full quality with NO transformations.
+ * Transformations are applied dynamically via URL at delivery time.
+ *
+ * Presets in Cloudinary dashboard:
+ * - ayezee_gallery: For gallery/fan-wall images → folder: gallery-images
+ * - ayezee_optimized: For project logos → folder: project-logos
+ */
+/**
+ * Build a Cloudinary URL with transformations
+ */
+export function buildCloudinaryUrl(url, options = {}) {
+    if (!url || !url.includes("cloudinary.com"))
+        return url;
+    const uploadIndex = url.indexOf("/upload/");
+    if (uploadIndex === -1)
+        return url;
+    const baseUrl = url.substring(0, uploadIndex + 8); // includes '/upload/'
+    const imagePath = url.substring(uploadIndex + 8);
+    const transforms = [];
+    // Format (most important for file size + quality)
+    if (options.format !== undefined) {
+        transforms.push(`f_${options.format}`);
+    }
+    else {
+        transforms.push("f_auto"); // Auto-select WebP/AVIF for modern browsers
+    }
+    // Quality
+    if (options.quality !== undefined) {
+        transforms.push(`q_${options.quality}`);
+    }
+    // Device pixel ratio (retina support)
+    if (options.dpr !== undefined) {
+        transforms.push(`dpr_${options.dpr}`);
+    }
+    else {
+        transforms.push("dpr_auto"); // Auto-detect retina displays
+    }
+    // Dimensions
+    if (options.width) {
+        transforms.push(`w_${options.width}`);
+    }
+    if (options.height) {
+        transforms.push(`h_${options.height}`);
+    }
+    if (options.aspectRatio) {
+        transforms.push(`ar_${options.aspectRatio}`);
+    }
+    // Cropping
+    if (options.crop) {
+        transforms.push(`c_${options.crop}`);
+    }
+    else if (options.width || options.height) {
+        transforms.push("c_limit"); // Don't upscale beyond original
+    }
+    // Gravity (for cropping)
+    if (options.gravity) {
+        transforms.push(`g_${options.gravity}`);
+    }
+    return `${baseUrl}${transforms.join(",")}/${imagePath}`;
+}
+/**
+ * Generate srcset for responsive images
+ */
+export function buildCloudinarySrcSet(url, widths, quality = "auto:good") {
+    return widths
+        .map((width) => `${buildCloudinaryUrl(url, { width, quality })} ${width}w`)
+        .join(", ");
+}
+/**
+ * Preset configurations for common use cases
+ */
+export const CLOUDINARY_PRESETS = {
+    // Project logos
+    logo: {
+        // Standard logo display
+        default: (url) => buildCloudinaryUrl(url, {
+            width: 400,
+            quality: "auto:good",
+            crop: "limit",
+        }),
+        // Small thumbnail (for lists)
+        thumb: (url) => buildCloudinaryUrl(url, {
+            width: 100,
+            height: 100,
+            quality: "auto:good",
+            crop: "fill",
+            gravity: "center",
+        }),
+        // Large (for hero sections)
+        large: (url) => buildCloudinaryUrl(url, {
+            width: 800,
+            quality: "auto:best",
+            crop: "limit",
+        }),
+    },
+    // Gallery images - high quality, responsive
+    gallery: {
+        // Default src (mobile-first, good balance)
+        src: (url) => buildCloudinaryUrl(url, {
+            width: 1000,
+            quality: "auto:good",
+            crop: "limit",
+        }),
+        // Full srcset for responsive images
+        srcset: (url) => buildCloudinarySrcSet(url, [600, 1000, 1400, 1800, 2400], // Wide range for all devices + retina
+        "auto:good"),
+        // Hero/featured images (highest quality)
+        hero: (url) => buildCloudinaryUrl(url, {
+            width: 2400,
+            quality: "auto:best",
+            crop: "limit",
+        }),
+        // Thumbnail (for grid previews in admin)
+        thumb: (url) => buildCloudinaryUrl(url, {
+            width: 400,
+            height: 300,
+            quality: "auto:eco",
+            crop: "fill",
+            gravity: "auto",
+        }),
+    },
+    // Avatar/profile images
+    avatar: (url) => buildCloudinaryUrl(url, {
+        width: 200,
+        height: 200,
+        quality: "auto:good",
+        crop: "fill",
+        gravity: "face",
+    }),
+};
+/**
+ * Helper to check if a URL is from Cloudinary
+ */
+export function isCloudinaryUrl(url) {
+    return url.includes("res.cloudinary.com") || url.includes("cloudinary.com");
+}
+/**
+ * Extract public ID from Cloudinary URL
+ */
+export function getCloudinaryPublicId(url) {
+    if (!isCloudinaryUrl(url))
+        return null;
+    const uploadIndex = url.indexOf("/upload/");
+    if (uploadIndex === -1)
+        return null;
+    const pathAfterUpload = url.substring(uploadIndex + 8);
+    // Remove file extension
+    return pathAfterUpload.replace(/\.[^.]+$/, "");
+}

package/dist/cms-helper.d.ts

@@ -48,7 +48,7 @@ export interface CachedModule {
     instanceKey: string;
     label: string;
     slug: string;
-    dataType: 'collection' | 'singleton' | 'submissions';
+    dataType: string;
     category: string;
     description?: string;
     icon?: string;

package/dist/index.d.ts

@@ -6,5 +6,6 @@
  * @packageDocumentation
  */
 export * from './cms-helper.js';
+export * from './cloudinary-utils.js';
 export { ayezeeCms, type AyezeeCmsOptions } from './integration.js';
 export { ayezeeCms as default } from './integration.js';

package/dist/index.js

@@ -7,6 +7,8 @@
  */
 // Export CMS helper functions and types
 export * from './cms-helper.js';
+// Export Cloudinary utilities
+export * from './cloudinary-utils.js';
 // Export integration
 export { ayezeeCms } from './integration.js';
 // Default export

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ayezee-astro-cms",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "AyeZee CMS integration for Astro with automatic data fetching, form handling, and validation",
   "type": "module",
   "main": "./dist/index.js",