@krantho/api 0.0.0-stage → 1.0.1

package/dist/image-optimizer.d.ts

@@ -0,0 +1,86 @@
+import type { MediaSection } from '@krantho/config';
+import type { ImageFormat, ImagePreset } from './image-presets.js';
+/** Result of normalizing an uploaded image */
+export interface NormalizeResult {
+    buffer: Buffer;
+    width: number;
+    height: number;
+    mimeType: string;
+}
+/** Result of generating an image variant */
+export interface VariantResult {
+    bytes: Buffer;
+    contentType: string;
+    width: number;
+    height: number;
+}
+/** Dimension overrides for cropping and hotspot */
+export interface DimensionOverrides {
+    aspectRatio?: string | undefined;
+    /** Crop region as percentages (0-100) — applied before resize */
+    crop?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    } | undefined;
+    /** Hotspot center + ellipse for adaptive aspect-ratio cropping (0-100%) */
+    hotspot?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    } | undefined;
+}
+/** Image processing settings, as the configuration tree declares them */
+export type ImageSettings = MediaSection['image'];
+/**
+ * Image processing pipeline using sharp.
+ *
+ * Handles upload normalization (EXIF, cap dimensions, JPEG re-encode)
+ * and on-demand variant generation (resize to preset, format conversion).
+ */
+export declare class ImageOptimizer {
+    private readonly settings;
+    private sharpFn;
+    constructor(settings: ImageSettings);
+    /**
+     * Normalize an uploaded image:
+     * 1. Auto-orient from EXIF
+     * 2. Cap width to maxWidth
+     * 3. Re-encode as JPEG at the configured normalize quality
+     *
+     * Returns the normalized buffer and detected dimensions.
+     * Skips normalization for SVG (returns input unchanged).
+     */
+    normalize(buffer: Uint8Array, mimeType: string): Promise<NormalizeResult>;
+    /**
+     * Generate a resized variant for serving.
+     *
+     * Resizes to the preset width (preserving aspect ratio) and encodes
+     * to the requested format. If overrides specify an aspect ratio,
+     * applies center crop before resizing.
+     */
+    generateVariant(buffer: Uint8Array, preset: ImagePreset, format: ImageFormat, overrides?: DimensionOverrides): Promise<VariantResult>;
+    /** Pixel width for a preset. Null means serve at the original size. */
+    private presetWidth;
+    /** Apply a percentage-based crop region, converting to pixel coordinates */
+    private applyCrop;
+    /**
+     * Hotspot-aware aspect crop: crop to a target aspect ratio, keeping the
+     * hotspot center visible. Then resize to target width.
+     *
+     * Only the hotspot center (x, y) is used for positioning. The hotspot
+     * width/height (ellipse) are stored for Studio visualization but do not
+     * affect the image processing.
+     *
+     * Example: a 3:2 landscape photo served as 1:1 thumbnail — the crop
+     * centers on the hotspot instead of the image center.
+     */
+    private applyHotspotCrop;
+    /** Lazy-load sharp to avoid loading native bindings until needed */
+    private getSharp;
+}
+/** Compute an ETag from image bytes (first 8 chars of SHA-256) */
+export declare function computeEtag(bytes: Uint8Array): string;
+//# sourceMappingURL=image-optimizer.d.ts.map

package/dist/image-optimizer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"image-optimizer.d.ts","sourceRoot":"","sources":["../src/image-optimizer.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAA;AAGnD,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAA;AAKlE,8CAA8C;AAC9C,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAA;IACd,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,MAAM,CAAA;IACd,QAAQ,EAAE,MAAM,CAAA;CACjB;AAED,4CAA4C;AAC5C,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAA;IACb,WAAW,EAAE,MAAM,CAAA;IACnB,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,MAAM,CAAA;CACf;AAED,mDAAmD;AACnD,MAAM,WAAW,kBAAkB;IACjC,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAChC,iEAAiE;IACjE,IAAI,CAAC,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS,CAAA;IAC1E,2EAA2E;IAC3E,OAAO,CAAC,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS,CAAA;CAC9E;AAED,yEAAyE;AACzE,MAAM,MAAM,aAAa,GAAG,YAAY,CAAC,OAAO,CAAC,CAAA;AAKjD;;;;;GAKG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAe;IACxC,OAAO,CAAC,OAAO,CAAqB;gBAExB,QAAQ,EAAE,aAAa;IAInC;;;;;;;;OAQG;IACG,SAAS,CAAC,MAAM,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC;IAyB/E;;;;;;OAMG;IACG,eAAe,CACnB,MAAM,EAAE,UAAU,EAClB,MAAM,EAAE,WAAW,EACnB,MAAM,EAAE,WAAW,EACnB,SAAS,CAAC,EAAE,kBAAkB,GAC7B,OAAO,CAAC,aAAa,CAAC;IA0EzB,uEAAuE;IACvE,OAAO,CAAC,WAAW;IAInB,4EAA4E;YAC9D,SAAS;IAmBvB;;;;;;;;;;OAUG;YACW,gBAAgB;IA2C9B,oEAAoE;YACtD,QAAQ;CAOvB;AAED,kEAAkE;AAClE,wBAAgB,WAAW,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAErD"}

package/dist/image-optimizer.js

@@ -0,0 +1,206 @@
+import { createHash } from 'node:crypto';
+import { getContentType } from './image-presets.js';
+// SVG should not be processed by sharp
+const SKIP_NORMALIZE_TYPES = new Set(['image/svg+xml']);
+/**
+ * Image processing pipeline using sharp.
+ *
+ * Handles upload normalization (EXIF, cap dimensions, JPEG re-encode)
+ * and on-demand variant generation (resize to preset, format conversion).
+ */
+export class ImageOptimizer {
+    settings;
+    sharpFn;
+    constructor(settings) {
+        this.settings = settings;
+    }
+    /**
+     * Normalize an uploaded image:
+     * 1. Auto-orient from EXIF
+     * 2. Cap width to maxWidth
+     * 3. Re-encode as JPEG at the configured normalize quality
+     *
+     * Returns the normalized buffer and detected dimensions.
+     * Skips normalization for SVG (returns input unchanged).
+     */
+    async normalize(buffer, mimeType) {
+        if (SKIP_NORMALIZE_TYPES.has(mimeType)) {
+            return {
+                buffer: Buffer.from(buffer),
+                width: 0,
+                height: 0,
+                mimeType,
+            };
+        }
+        const sharpFn = await this.getSharp();
+        const result = await sharpFn(Buffer.from(buffer))
+            .rotate() // Auto-orient from EXIF
+            .resize({ width: this.settings.maxWidth, withoutEnlargement: true })
+            .jpeg({ quality: this.settings.quality.normalize })
+            .toBuffer({ resolveWithObject: true });
+        return {
+            buffer: result.data,
+            width: result.info.width,
+            height: result.info.height,
+            mimeType: 'image/jpeg',
+        };
+    }
+    /**
+     * Generate a resized variant for serving.
+     *
+     * Resizes to the preset width (preserving aspect ratio) and encodes
+     * to the requested format. If overrides specify an aspect ratio,
+     * applies center crop before resizing.
+     */
+    async generateVariant(buffer, preset, format, overrides) {
+        const sharpFn = await this.getSharp();
+        const targetWidth = this.presetWidth(preset);
+        let pipeline = sharpFn(Buffer.from(buffer)).rotate();
+        // Hotspot-aware aspect crop takes precedence over explicit crop — they are
+        // mutually exclusive because hotspot crop operates on the original image coordinates.
+        if (overrides?.hotspot && overrides.aspectRatio && targetWidth) {
+            const [wRatio, hRatio] = parseAspectRatio(overrides.aspectRatio);
+            if (wRatio && hRatio) {
+                pipeline = await this.applyHotspotCrop(pipeline, buffer, overrides.hotspot, wRatio / hRatio, targetWidth);
+            }
+        }
+        else {
+            // Apply percentage-based crop region when hotspot+aspect is not active
+            if (overrides?.crop) {
+                pipeline = await this.applyCrop(pipeline, buffer, overrides.crop);
+            }
+            if (overrides?.aspectRatio) {
+                // Apply explicit aspect ratio crop
+                const [wRatio, hRatio] = parseAspectRatio(overrides.aspectRatio);
+                if (wRatio && hRatio && targetWidth) {
+                    const targetHeight = Math.round(targetWidth * (hRatio / wRatio));
+                    pipeline = pipeline.resize({
+                        width: targetWidth,
+                        height: targetHeight,
+                        fit: 'cover',
+                    });
+                }
+            }
+            else if (targetWidth) {
+                // Standard resize — preserve aspect ratio, no upscaling
+                pipeline = pipeline.resize({
+                    width: targetWidth,
+                    withoutEnlargement: true,
+                });
+            }
+            // 'full' preset: no resize at all
+        }
+        // Encode to target format
+        switch (format) {
+            case 'webp':
+                pipeline = pipeline.webp({ quality: this.settings.quality.webp });
+                break;
+            case 'jpeg':
+                pipeline = pipeline.jpeg({ quality: this.settings.quality.jpeg });
+                break;
+            case 'png':
+                pipeline = pipeline.png();
+                break;
+            case 'avif':
+                pipeline = pipeline.avif({ quality: this.settings.quality.avif });
+                break;
+        }
+        const result = await pipeline.toBuffer({ resolveWithObject: true });
+        const contentType = getContentType(format);
+        return {
+            bytes: result.data,
+            contentType,
+            width: result.info.width,
+            height: result.info.height,
+        };
+    }
+    /** Pixel width for a preset. Null means serve at the original size. */
+    presetWidth(preset) {
+        return this.settings.presets[preset] ?? null;
+    }
+    /** Apply a percentage-based crop region, converting to pixel coordinates */
+    async applyCrop(pipeline, buffer, crop) {
+        const sharpFn = await this.getSharp();
+        const metadata = await sharpFn(Buffer.from(buffer)).metadata();
+        if (metadata.width && metadata.height) {
+            const left = Math.round((crop.x / 100) * metadata.width);
+            const top = Math.round((crop.y / 100) * metadata.height);
+            const width = Math.round((crop.width / 100) * metadata.width);
+            const height = Math.round((crop.height / 100) * metadata.height);
+            if (width > 0 && height > 0) {
+                return pipeline.extract({ left, top, width, height });
+            }
+        }
+        return pipeline;
+    }
+    /**
+     * Hotspot-aware aspect crop: crop to a target aspect ratio, keeping the
+     * hotspot center visible. Then resize to target width.
+     *
+     * Only the hotspot center (x, y) is used for positioning. The hotspot
+     * width/height (ellipse) are stored for Studio visualization but do not
+     * affect the image processing.
+     *
+     * Example: a 3:2 landscape photo served as 1:1 thumbnail — the crop
+     * centers on the hotspot instead of the image center.
+     */
+    async applyHotspotCrop(pipeline, buffer, hotspot, targetAspect, targetWidth) {
+        const sharpFn = await this.getSharp();
+        const metadata = await sharpFn(Buffer.from(buffer)).metadata();
+        if (!metadata.width || !metadata.height)
+            return pipeline;
+        const srcW = metadata.width;
+        const srcH = metadata.height;
+        const srcAspect = srcW / srcH;
+        // Compute the largest crop region at the target aspect that fits the source
+        let cropW;
+        let cropH;
+        if (targetAspect > srcAspect) {
+            // Target is wider — constrain by width
+            cropW = srcW;
+            cropH = Math.round(srcW / targetAspect);
+        }
+        else {
+            // Target is taller — constrain by height
+            cropH = srcH;
+            cropW = Math.round(srcH * targetAspect);
+        }
+        // Hotspot center in pixels
+        const hotX = Math.round((hotspot.x / 100) * srcW);
+        const hotY = Math.round((hotspot.y / 100) * srcH);
+        // Center crop on hotspot, clamp to image bounds
+        let left = Math.round(hotX - cropW / 2);
+        let top = Math.round(hotY - cropH / 2);
+        left = Math.max(0, Math.min(left, srcW - cropW));
+        top = Math.max(0, Math.min(top, srcH - cropH));
+        return pipeline
+            .extract({ left, top, width: cropW, height: cropH })
+            .resize({ width: targetWidth, withoutEnlargement: true });
+    }
+    /** Lazy-load sharp to avoid loading native bindings until needed */
+    async getSharp() {
+        if (!this.sharpFn) {
+            const mod = await import('sharp');
+            this.sharpFn = mod.default;
+        }
+        return this.sharpFn;
+    }
+}
+/** Compute an ETag from image bytes (first 8 chars of SHA-256) */
+export function computeEtag(bytes) {
+    return createHash('sha256').update(bytes).digest('hex').slice(0, 16);
+}
+/** Parse an aspect ratio string like '16:9' into [16, 9] */
+function parseAspectRatio(ratio) {
+    const parts = ratio.split(':');
+    const rawW = parts[0];
+    const rawH = parts[1];
+    if (parts.length !== 2 || !rawW || !rawH)
+        return [undefined, undefined];
+    const w = Number.parseInt(rawW, 10);
+    const h = Number.parseInt(rawH, 10);
+    if (Number.isNaN(w) || Number.isNaN(h) || w <= 0 || h <= 0)
+        return [undefined, undefined];
+    return [w, h];
+}
+//# sourceMappingURL=image-optimizer.js.map

package/dist/image-optimizer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"image-optimizer.js","sourceRoot":"","sources":["../src/image-optimizer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAKxC,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAA;AAgCnD,uCAAuC;AACvC,MAAM,oBAAoB,GAAG,IAAI,GAAG,CAAC,CAAC,eAAe,CAAC,CAAC,CAAA;AAEvD;;;;;GAKG;AACH,MAAM,OAAO,cAAc;IACR,QAAQ,CAAe;IAChC,OAAO,CAAqB;IAEpC,YAAY,QAAuB;QACjC,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAA;IAC1B,CAAC;IAED;;;;;;;;OAQG;IACH,KAAK,CAAC,SAAS,CAAC,MAAkB,EAAE,QAAgB;QAClD,IAAI,oBAAoB,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC;YACvC,OAAO;gBACL,MAAM,EAAE,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC;gBAC3B,KAAK,EAAE,CAAC;gBACR,MAAM,EAAE,CAAC;gBACT,QAAQ;aACT,CAAA;QACH,CAAC;QAED,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,QAAQ,EAAE,CAAA;QACrC,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;aAC9C,MAAM,EAAE,CAAC,wBAAwB;aACjC,MAAM,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,QAAQ,CAAC,QAAQ,EAAE,kBAAkB,EAAE,IAAI,EAAE,CAAC;aACnE,IAAI,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,SAAS,EAAE,CAAC;aAClD,QAAQ,CAAC,EAAE,iBAAiB,EAAE,IAAI,EAAE,CAAC,CAAA;QAExC,OAAO;YACL,MAAM,EAAE,MAAM,CAAC,IAAI;YACnB,KAAK,EAAE,MAAM,CAAC,IAAI,CAAC,KAAK;YACxB,MAAM,EAAE,MAAM,CAAC,IAAI,CAAC,MAAM;YAC1B,QAAQ,EAAE,YAAY;SACvB,CAAA;IACH,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,eAAe,CACnB,MAAkB,EAClB,MAAmB,EACnB,MAAmB,EACnB,SAA8B;QAE9B,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,QAAQ,EAAE,CAAA;QACrC,MAAM,WAAW,GAAG,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,CAAA;QAE5C,IAAI,QAAQ,GAAG,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,CAAA;QAEpD,2EAA2E;QAC3E,sFAAsF;QACtF,IAAI,SAAS,EAAE,OAAO,IAAI,SAAS,CAAC,WAAW,IAAI,WAAW,EAAE,CAAC;YAC/D,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,gBAAgB,CAAC,SAAS,CAAC,WAAW,CAAC,CAAA;YAChE,IAAI,MAAM,IAAI,MAAM,EAAE,CAAC;gBACrB,QAAQ,GAAG,MAAM,IAAI,CAAC,gBAAgB,CACpC,QAAQ,EACR,MAAM,EACN,SAAS,CAAC,OAAO,EACjB,MAAM,GAAG,MAAM,EACf,WAAW,CACZ,CAAA;YACH,CAAC;QACH,CAAC;aAAM,CAAC;YACN,uEAAuE;YACvE,IAAI,SAAS,EAAE,IAAI,EAAE,CAAC;gBACpB,QAAQ,GAAG,MAAM,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,CAAC,IAAI,CAAC,CAAA;YACnE,CAAC;YAED,IAAI,SAAS,EAAE,WAAW,EAAE,CAAC;gBAC3B,mCAAmC;gBACnC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,gBAAgB,CAAC,SAAS,CAAC,WAAW,CAAC,CAAA;gBAChE,IAAI,MAAM,IAAI,MAAM,IAAI,WAAW,EAAE,CAAC;oBACpC,MAAM,YAAY,GAAG,IAAI,CAAC,KAAK,CAAC,WAAW,GAAG,CAAC,MAAM,GAAG,MAAM,CAAC,CAAC,CAAA;oBAChE,QAAQ,GAAG,QAAQ,CAAC,MAAM,CAAC;wBACzB,KAAK,EAAE,WAAW;wBAClB,MAAM,EAAE,YAAY;wBACpB,GAAG,EAAE,OAAO;qBACb,CAAC,CAAA;gBACJ,CAAC;YACH,CAAC;iBAAM,IAAI,WAAW,EAAE,CAAC;gBACvB,wDAAwD;gBACxD,QAAQ,GAAG,QAAQ,CAAC,MAAM,CAAC;oBACzB,KAAK,EAAE,WAAW;oBAClB,kBAAkB,EAAE,IAAI;iBACzB,CAAC,CAAA;YACJ,CAAC;YACD,kCAAkC;QACpC,CAAC;QAED,0BAA0B;QAC1B,QAAQ,MAAM,EAAE,CAAC;YACf,KAAK,MAAM;gBACT,QAAQ,GAAG,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,CAAA;gBACjE,MAAK;YACP,KAAK,MAAM;gBACT,QAAQ,GAAG,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,CAAA;gBACjE,MAAK;YACP,KAAK,KAAK;gBACR,QAAQ,GAAG,QAAQ,CAAC,GAAG,EAAE,CAAA;gBACzB,MAAK;YACP,KAAK,MAAM;gBACT,QAAQ,GAAG,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,CAAA;gBACjE,MAAK;QACT,CAAC;QAED,MAAM,MAAM,GAAG,MAAM,QAAQ,CAAC,QAAQ,CAAC,EAAE,iBAAiB,EAAE,IAAI,EAAE,CAAC,CAAA;QAEnE,MAAM,WAAW,GAAG,cAAc,CAAC,MAAM,CAAC,CAAA;QAE1C,OAAO;YACL,KAAK,EAAE,MAAM,CAAC,IAAI;YAClB,WAAW;YACX,KAAK,EAAE,MAAM,CAAC,IAAI,CAAC,KAAK;YACxB,MAAM,EAAE,MAAM,CAAC,IAAI,CAAC,MAAM;SAC3B,CAAA;IACH,CAAC;IAED,uEAAuE;IAC/D,WAAW,CAAC,MAAmB;QACrC,OAAO,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,IAAI,CAAA;IAC9C,CAAC;IAED,4EAA4E;IACpE,KAAK,CAAC,SAAS,CACrB,QAAe,EACf,MAAkB,EAClB,IAA6D;QAE7D,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,QAAQ,EAAE,CAAA;QACrC,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAA;QAC9D,IAAI,QAAQ,CAAC,KAAK,IAAI,QAAQ,CAAC,MAAM,EAAE,CAAC;YACtC,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,GAAG,CAAC,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAA;YACxD,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,GAAG,CAAC,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAA;YACxD,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,KAAK,GAAG,GAAG,CAAC,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAA;YAC7D,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,MAAM,GAAG,GAAG,CAAC,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAA;YAChE,IAAI,KAAK,GAAG,CAAC,IAAI,MAAM,GAAG,CAAC,EAAE,CAAC;gBAC5B,OAAO,QAAQ,CAAC,OAAO,CAAC,EAAE,IAAI,EAAE,GAAG,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,CAAA;YACvD,CAAC;QACH,CAAC;QACD,OAAO,QAAQ,CAAA;IACjB,CAAC;IAED;;;;;;;;;;OAUG;IACK,KAAK,CAAC,gBAAgB,CAC5B,QAAe,EACf,MAAkB,EAClB,OAAgE,EAChE,YAAoB,EACpB,WAAmB;QAEnB,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,QAAQ,EAAE,CAAA;QACrC,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAA;QAC9D,IAAI,CAAC,QAAQ,CAAC,KAAK,IAAI,CAAC,QAAQ,CAAC,MAAM;YAAE,OAAO,QAAQ,CAAA;QAExD,MAAM,IAAI,GAAG,QAAQ,CAAC,KAAK,CAAA;QAC3B,MAAM,IAAI,GAAG,QAAQ,CAAC,MAAM,CAAA;QAC5B,MAAM,SAAS,GAAG,IAAI,GAAG,IAAI,CAAA;QAE7B,4EAA4E;QAC5E,IAAI,KAAa,CAAA;QACjB,IAAI,KAAa,CAAA;QACjB,IAAI,YAAY,GAAG,SAAS,EAAE,CAAC;YAC7B,uCAAuC;YACvC,KAAK,GAAG,IAAI,CAAA;YACZ,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,GAAG,YAAY,CAAC,CAAA;QACzC,CAAC;aAAM,CAAC;YACN,yCAAyC;YACzC,KAAK,GAAG,IAAI,CAAA;YACZ,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,GAAG,YAAY,CAAC,CAAA;QACzC,CAAC;QAED,2BAA2B;QAC3B,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,OAAO,CAAC,CAAC,GAAG,GAAG,CAAC,GAAG,IAAI,CAAC,CAAA;QACjD,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,OAAO,CAAC,CAAC,GAAG,GAAG,CAAC,GAAG,IAAI,CAAC,CAAA;QAEjD,gDAAgD;QAChD,IAAI,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,GAAG,KAAK,GAAG,CAAC,CAAC,CAAA;QACvC,IAAI,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,GAAG,KAAK,GAAG,CAAC,CAAC,CAAA;QACtC,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,GAAG,KAAK,CAAC,CAAC,CAAA;QAChD,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,GAAG,KAAK,CAAC,CAAC,CAAA;QAE9C,OAAO,QAAQ;aACZ,OAAO,CAAC,EAAE,IAAI,EAAE,GAAG,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;aACnD,MAAM,CAAC,EAAE,KAAK,EAAE,WAAW,EAAE,kBAAkB,EAAE,IAAI,EAAE,CAAC,CAAA;IAC7D,CAAC;IAED,oEAAoE;IAC5D,KAAK,CAAC,QAAQ;QACpB,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC;YAClB,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,OAAO,CAAC,CAAA;YACjC,IAAI,CAAC,OAAO,GAAG,GAAG,CAAC,OAAO,CAAA;QAC5B,CAAC;QACD,OAAO,IAAI,CAAC,OAAO,CAAA;IACrB,CAAC;CACF;AAED,kEAAkE;AAClE,MAAM,UAAU,WAAW,CAAC,KAAiB;IAC3C,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAA;AACtE,CAAC;AAED,4DAA4D;AAC5D,SAAS,gBAAgB,CAAC,KAAa;IACrC,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAA;IAC9B,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,CAAA;IACrB,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,CAAA;IACrB,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,IAAI;QAAE,OAAO,CAAC,SAAS,EAAE,SAAS,CAAC,CAAA;IACvE,MAAM,CAAC,GAAG,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE,EAAE,CAAC,CAAA;IACnC,MAAM,CAAC,GAAG,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE,EAAE,CAAC,CAAA;IACnC,IAAI,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC;QAAE,OAAO,CAAC,SAAS,EAAE,SAAS,CAAC,CAAA;IACzF,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC,CAAA;AACf,CAAC"}

package/dist/image-presets.d.ts

@@ -0,0 +1,17 @@
+/** Image size presets — fixed classes, not arbitrary dimensions */
+export type ImagePreset = 'xs' | 'sm' | 'md' | 'lg' | 'xl' | 'full';
+/** Supported output formats */
+export type ImageFormat = 'webp' | 'jpeg' | 'png' | 'avif';
+/** Parse and validate a preset string. Returns 'md' as default. */
+export declare function parsePreset(value: string | undefined): ImagePreset;
+/** Parse and validate a format string. Negotiates from Accept header if not explicit. */
+export declare function parseFormat(value: string | undefined, acceptHeader: string | undefined): ImageFormat;
+/** Get the content type for a format */
+export declare function getContentType(format: ImageFormat): string;
+/**
+ * Clamp an arbitrary pixel width to the nearest preset.
+ *
+ * 0–64 → xs, 65–160 → sm, 161–384 → md, 385–768 → lg, 769+ → xl
+ */
+export declare function clampToPreset(width: number): ImagePreset;
+//# sourceMappingURL=image-presets.d.ts.map

package/dist/image-presets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"image-presets.d.ts","sourceRoot":"","sources":["../src/image-presets.ts"],"names":[],"mappings":"AAAA,mEAAmE;AACnE,MAAM,MAAM,WAAW,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,MAAM,CAAA;AAEnE,+BAA+B;AAC/B,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,MAAM,GAAG,KAAK,GAAG,MAAM,CAAA;AAY1D,mEAAmE;AACnE,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,WAAW,CAGlE;AAED,yFAAyF;AACzF,wBAAgB,WAAW,CACzB,KAAK,EAAE,MAAM,GAAG,SAAS,EACzB,YAAY,EAAE,MAAM,GAAG,SAAS,GAC/B,WAAW,CAWb;AAED,wCAAwC;AACxC,wBAAgB,cAAc,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,CAE1D;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,WAAW,CAMxD"}

package/dist/image-presets.js

@@ -0,0 +1,50 @@
+const PRESET_NAMES = new Set(['xs', 'sm', 'md', 'lg', 'xl', 'full']);
+const FORMAT_NAMES = new Set(['webp', 'jpeg', 'png', 'avif']);
+const FORMAT_CONTENT_TYPES = {
+    webp: 'image/webp',
+    jpeg: 'image/jpeg',
+    png: 'image/png',
+    avif: 'image/avif',
+};
+/** Parse and validate a preset string. Returns 'md' as default. */
+export function parsePreset(value) {
+    if (value && PRESET_NAMES.has(value))
+        return value;
+    return 'md';
+}
+/** Parse and validate a format string. Negotiates from Accept header if not explicit. */
+export function parseFormat(value, acceptHeader) {
+    if (value && FORMAT_NAMES.has(value))
+        return value;
+    // Negotiate from Accept header — prefer AVIF (smallest), then WebP
+    if (acceptHeader) {
+        if (acceptHeader.includes('image/avif'))
+            return 'avif';
+        if (acceptHeader.includes('image/webp'))
+            return 'webp';
+        if (acceptHeader.includes('image/png'))
+            return 'png';
+    }
+    return 'avif'; // default — best compression
+}
+/** Get the content type for a format */
+export function getContentType(format) {
+    return FORMAT_CONTENT_TYPES[format];
+}
+/**
+ * Clamp an arbitrary pixel width to the nearest preset.
+ *
+ * 0–64 → xs, 65–160 → sm, 161–384 → md, 385–768 → lg, 769+ → xl
+ */
+export function clampToPreset(width) {
+    if (width <= 64)
+        return 'xs';
+    if (width <= 160)
+        return 'sm';
+    if (width <= 384)
+        return 'md';
+    if (width <= 768)
+        return 'lg';
+    return 'xl';
+}
+//# sourceMappingURL=image-presets.js.map

package/dist/image-presets.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"image-presets.js","sourceRoot":"","sources":["../src/image-presets.ts"],"names":[],"mappings":"AAMA,MAAM,YAAY,GAAG,IAAI,GAAG,CAAS,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC,CAAA;AAC5E,MAAM,YAAY,GAAG,IAAI,GAAG,CAAS,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC,CAAA;AAErE,MAAM,oBAAoB,GAAgC;IACxD,IAAI,EAAE,YAAY;IAClB,IAAI,EAAE,YAAY;IAClB,GAAG,EAAE,WAAW;IAChB,IAAI,EAAE,YAAY;CACnB,CAAA;AAED,mEAAmE;AACnE,MAAM,UAAU,WAAW,CAAC,KAAyB;IACnD,IAAI,KAAK,IAAI,YAAY,CAAC,GAAG,CAAC,KAAK,CAAC;QAAE,OAAO,KAAoB,CAAA;IACjE,OAAO,IAAI,CAAA;AACb,CAAC;AAED,yFAAyF;AACzF,MAAM,UAAU,WAAW,CACzB,KAAyB,EACzB,YAAgC;IAEhC,IAAI,KAAK,IAAI,YAAY,CAAC,GAAG,CAAC,KAAK,CAAC;QAAE,OAAO,KAAoB,CAAA;IAEjE,mEAAmE;IACnE,IAAI,YAAY,EAAE,CAAC;QACjB,IAAI,YAAY,CAAC,QAAQ,CAAC,YAAY,CAAC;YAAE,OAAO,MAAM,CAAA;QACtD,IAAI,YAAY,CAAC,QAAQ,CAAC,YAAY,CAAC;YAAE,OAAO,MAAM,CAAA;QACtD,IAAI,YAAY,CAAC,QAAQ,CAAC,WAAW,CAAC;YAAE,OAAO,KAAK,CAAA;IACtD,CAAC;IAED,OAAO,MAAM,CAAA,CAAC,6BAA6B;AAC7C,CAAC;AAED,wCAAwC;AACxC,MAAM,UAAU,cAAc,CAAC,MAAmB;IAChD,OAAO,oBAAoB,CAAC,MAAM,CAAC,CAAA;AACrC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAAC,KAAa;IACzC,IAAI,KAAK,IAAI,EAAE;QAAE,OAAO,IAAI,CAAA;IAC5B,IAAI,KAAK,IAAI,GAAG;QAAE,OAAO,IAAI,CAAA;IAC7B,IAAI,KAAK,IAAI,GAAG;QAAE,OAAO,IAAI,CAAA;IAC7B,IAAI,KAAK,IAAI,GAAG;QAAE,OAAO,IAAI,CAAA;IAC7B,OAAO,IAAI,CAAA;AACb,CAAC"}

package/dist/image-url.d.ts

@@ -0,0 +1,26 @@
+import type { MediaItem } from '@krantho/persistence';
+import type { ImageFormat, ImagePreset } from './image-presets.js';
+/** One concrete rendition of a media item: every choice made, nothing negotiated */
+export interface ImageVariant {
+    preset: ImagePreset;
+    /** `original` serves the stored bytes unchanged (SVG without a raster format) */
+    format: ImageFormat | 'original';
+    aspect: string | undefined;
+}
+/**
+ * The item's image revision: changes when the bytes or their framing change
+ * (a replace gives a new url; crop and hotspot reshape every variant), and
+ * stays put for alt text, tags, folder and rename edits.
+ */
+export declare function imageRevision(item: MediaItem): string;
+/**
+ * Resolve a request's variant: `w` maps to a preset, `fmt` is explicit or
+ * negotiated from `Accept`, and an SVG without an explicit raster format is
+ * served as the original.
+ */
+export declare function resolveVariant(item: MediaItem, query: Record<string, string | undefined>, headers?: Record<string, string> | undefined): ImageVariant;
+/** The versioned, immutable URL of a variant at a revision */
+export declare function variantUrl(id: string, variant: ImageVariant, rev: string): string;
+/** The in-memory cache key of a rendered variant; a new revision never hits an old entry */
+export declare function variantCacheKey(id: string, variant: ImageVariant, rev: string): string;
+//# sourceMappingURL=image-url.d.ts.map

package/dist/image-url.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"image-url.d.ts","sourceRoot":"","sources":["../src/image-url.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAA;AACrD,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAA;AAGlE,oFAAoF;AACpF,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,WAAW,CAAA;IACnB,iFAAiF;IACjF,MAAM,EAAE,WAAW,GAAG,UAAU,CAAA;IAChC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAA;CAC3B;AAOD;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM,CAGrD;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,SAAS,EACf,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,EACzC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,GAC3C,YAAY,CAId;AAED,8DAA8D;AAC9D,wBAAgB,UAAU,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAGjF;AAED,4FAA4F;AAC5F,wBAAgB,eAAe,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAEtF"}

package/dist/image-url.js

@@ -0,0 +1,47 @@
+import { createHash } from 'node:crypto';
+import { clampToPreset, parseFormat, parsePreset } from './image-presets.js';
+const SVG = 'image/svg+xml';
+const FORMATS = new Set(['webp', 'jpeg', 'png', 'avif']);
+/** Only N:N ratios, so arbitrary values cannot flood the variant cache */
+const ASPECT_PATTERN = /^\d+:\d+$/;
+/**
+ * The item's image revision: changes when the bytes or their framing change
+ * (a replace gives a new url; crop and hotspot reshape every variant), and
+ * stays put for alt text, tags, folder and rename edits.
+ */
+export function imageRevision(item) {
+    const source = `${item.url}|${JSON.stringify(item.crop)}|${JSON.stringify(item.hotspot)}`;
+    return createHash('sha256').update(source).digest('hex').slice(0, 12);
+}
+/**
+ * Resolve a request's variant: `w` maps to a preset, `fmt` is explicit or
+ * negotiated from `Accept`, and an SVG without an explicit raster format is
+ * served as the original.
+ */
+export function resolveVariant(item, query, headers) {
+    const rawAspect = query['aspect'];
+    const aspect = rawAspect && ASPECT_PATTERN.test(rawAspect) ? rawAspect : undefined;
+    return { preset: resolvePreset(query), format: resolveFormat(item, query, headers), aspect };
+}
+/** The versioned, immutable URL of a variant at a revision */
+export function variantUrl(id, variant, rev) {
+    const aspect = variant.aspect ? `&aspect=${variant.aspect}` : '';
+    return `/api/media/${encodeURIComponent(id)}/image?preset=${variant.preset}&fmt=${variant.format}${aspect}&rev=${rev}`;
+}
+/** The in-memory cache key of a rendered variant; a new revision never hits an old entry */
+export function variantCacheKey(id, variant, rev) {
+    return `${id}/${rev}/${variant.preset}/${variant.format}/${variant.aspect ?? ''}`;
+}
+function resolvePreset(query) {
+    const rawW = query['w'];
+    const width = rawW ? Number.parseInt(rawW, 10) : Number.NaN;
+    return Number.isNaN(width) ? parsePreset(query['preset']) : clampToPreset(width);
+}
+function resolveFormat(item, query, headers) {
+    const fmt = query['fmt'];
+    const explicitRaster = fmt !== undefined && FORMATS.has(fmt);
+    if (item.mimeType === SVG && !explicitRaster)
+        return 'original';
+    return parseFormat(fmt, headers?.['accept']);
+}
+//# sourceMappingURL=image-url.js.map

package/dist/image-url.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"image-url.js","sourceRoot":"","sources":["../src/image-url.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,37 @@
+export type { AssistantActivity, AssistantChatRequest, AssistantDoneReason, AssistantErrorCode, AssistantEvent, DocumentChange, DocumentRef, FieldChange, PendingActionKind, PendingActionView, SeoFinding, } from './assistant/protocol.js';
+export { deliverChange, deliverChanges } from './content-change.js';
+export { accessCookieName, buildCookie, refreshCookieName } from './cookies.js';
+export type { ApiHandlers, CreateApiHandlersConfig } from './create-api-handlers.js';
+export { createApiHandlers } from './create-api-handlers.js';
+export { createContent, deleteContent, getContent, getSchema, getVersion, listCollection, listCollections, listContent, listContentTree, listVersions, mediaDelete, mediaGet, mediaImage, mediaImageInfo, mediaList, mediaRegister, mediaUpdate, mediaUpload, publishContent, resolvePageRoute, restoreVersion, updateContent, validateAll, } from './handlers/index.js';
+export { storedBaseUrlSetting, storedModelSetting } from './handlers/llm-credential.js';
+export type { AfterMutationContext, BeforeSaveContext, ContentHooks } from './hooks.js';
+export type { CachedVariant, ImageCacheSettings } from './image-cache.js';
+export { ImageCache } from './image-cache.js';
+export type { ImageDimensions } from './image-dimensions.js';
+export { detectDimensions } from './image-dimensions.js';
+export type { ImageSettings } from './image-optimizer.js';
+export { ImageOptimizer } from './image-optimizer.js';
+export type { ImageFormat, ImagePreset } from './image-presets.js';
+export { clampToPreset, getContentType, parseFormat, parsePreset, } from './image-presets.js';
+export type { ImageVariant } from './image-url.js';
+export { imageRevision, resolveVariant, variantUrl } from './image-url.js';
+export type { JwtClaims } from './jwt.js';
+export { resolveJwtSecret, verifyJwt } from './jwt.js';
+export type { MediaLibrarySettings } from './media-library.js';
+export { MediaLibrary } from './media-library.js';
+export type { AuthResult } from './middleware/auth.js';
+export { checkAuth } from './middleware/auth.js';
+export type { KranthoPlugin, PluginFieldType, PluginRegistry, PluginRoute, PluginStudioPage, } from './plugins.js';
+export { loadPlugins } from './plugins.js';
+export { PREVIEW_PARAM, verifyPreviewToken } from './preview-token.js';
+export { ApiRouter } from './router.js';
+export type { PageJsonLdInput } from './seo-compose.js';
+export { composePageJsonLd } from './seo-compose.js';
+export { startSeo } from './seo-subsystem.js';
+export type { ApiContext, ApiHandler, ApiRequest, ApiResponse, AuthenticatedUser, ContentItemResponse, ErrorResponse, MediaConfig, ServerFramework, SitePreviewMode, WebhookConfig, } from './types.js';
+export { hasVersioning } from './types.js';
+export { parseCookie } from './validators.js';
+export { processWebhookRetries } from './webhooks.js';
+export { checkWorkloadAuth, WORKLOAD_PATHS } from './workload-identity.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -0,0 +1,23 @@
+export { deliverChange, deliverChanges } from './content-change.js';
+export { accessCookieName, buildCookie, refreshCookieName } from './cookies.js';
+export { createApiHandlers } from './create-api-handlers.js';
+export { createContent, deleteContent, getContent, getSchema, getVersion, listCollection, listCollections, listContent, listContentTree, listVersions, mediaDelete, mediaGet, mediaImage, mediaImageInfo, mediaList, mediaRegister, mediaUpdate, mediaUpload, publishContent, resolvePageRoute, restoreVersion, updateContent, validateAll, } from './handlers/index.js';
+export { storedBaseUrlSetting, storedModelSetting } from './handlers/llm-credential.js';
+export { ImageCache } from './image-cache.js';
+export { detectDimensions } from './image-dimensions.js';
+export { ImageOptimizer } from './image-optimizer.js';
+export { clampToPreset, getContentType, parseFormat, parsePreset, } from './image-presets.js';
+export { imageRevision, resolveVariant, variantUrl } from './image-url.js';
+export { resolveJwtSecret, verifyJwt } from './jwt.js';
+export { MediaLibrary } from './media-library.js';
+export { checkAuth } from './middleware/auth.js';
+export { loadPlugins } from './plugins.js';
+export { PREVIEW_PARAM, verifyPreviewToken } from './preview-token.js';
+export { ApiRouter } from './router.js';
+export { composePageJsonLd } from './seo-compose.js';
+export { startSeo } from './seo-subsystem.js';
+export { hasVersioning } from './types.js';
+export { parseCookie } from './validators.js';
+export { processWebhookRetries } from './webhooks.js';
+export { checkWorkloadAuth, WORKLOAD_PATHS } from './workload-identity.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAaA,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAA;AACnE,OAAO,EAAE,gBAAgB,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAA;AAE/E,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAA;AAC5D,OAAO,EACL,aAAa,EACb,aAAa,EACb,UAAU,EACV,SAAS,EACT,UAAU,EACV,cAAc,EACd,eAAe,EACf,WAAW,EACX,eAAe,EACf,YAAY,EACZ,WAAW,EACX,QAAQ,EACR,UAAU,EACV,cAAc,EACd,SAAS,EACT,aAAa,EACb,WAAW,EACX,WAAW,EACX,cAAc,EACd,gBAAgB,EAChB,cAAc,EACd,aAAa,EACb,WAAW,GACZ,MAAM,qBAAqB,CAAA;AAC5B,OAAO,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,MAAM,8BAA8B,CAAA;AAGvF,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAE7C,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAA;AAExD,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AAErD,OAAO,EACL,aAAa,EACb,cAAc,EACd,WAAW,EACX,WAAW,GACZ,MAAM,oBAAoB,CAAA;AAE3B,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAA;AAE1E,OAAO,EAAE,gBAAgB,EAAE,SAAS,EAAE,MAAM,UAAU,CAAA;AAEtD,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AAEjD,OAAO,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAA;AAQhD,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAA;AAC1C,OAAO,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAA;AACtE,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AAEvC,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAA;AACpD,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAA;AAc7C,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAC1C,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAA;AAC7C,OAAO,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAA;AACrD,OAAO,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAA"}

package/dist/jwt.d.ts

@@ -0,0 +1,54 @@
+import type { AuthSection } from '@krantho/config';
+import type { Role } from '@krantho/persistence';
+/** Claims embedded in a krantho access token JWT */
+export interface JwtClaims {
+    /** User ID (UUID) */
+    sub: string;
+    /** User email */
+    email: string;
+    /** Display name */
+    name: string;
+    /** Assigned roles */
+    roles: Role[];
+    /** Issued at (unix seconds) */
+    iat: number;
+    /** Expires at (unix seconds) */
+    exp: number;
+}
+/** Result of verifying a JWT */
+export type VerifyResult = {
+    valid: true;
+    claims: JwtClaims;
+} | {
+    valid: false;
+    error: string;
+};
+/**
+ * Sign a JWT with HS256.
+ *
+ * @param claims - Token claims (sub, email, name, roles)
+ * @param secret - HMAC secret (`config.auth.jwtSecret`)
+ * @param expiresInSeconds - Token lifetime in seconds (default: 900 = 15 minutes)
+ */
+export declare function signJwt(claims: Omit<JwtClaims, 'iat' | 'exp'>, secret: string, expiresInSeconds?: number): string;
+/**
+ * Verify a JWT signature and check expiry.
+ *
+ * @param token - The full JWT string
+ * @param secret - HMAC secret (must match the signing secret)
+ */
+export declare function verifyJwt(token: string, secret: string): VerifyResult;
+/** Generate a cryptographically random refresh token (64 hex chars) */
+export declare function generateRefreshToken(): string;
+/** Hash a refresh token for database storage */
+export declare function hashRefreshToken(token: string, secret: string): string;
+/** Generate a random JWT secret (for dev mode when none is configured) */
+export declare function generateJwtSecret(): string;
+/**
+ * The effective signing secret: the configured one (KRANTHO_JWT_SECRET beats a
+ * `jwtSecret` set in code, as the config tree resolves it), or, when neither is
+ * set, one ephemeral secret for the whole process — generated with a warning —
+ * so the API and the pages it serves (a signed preview link) agree on it.
+ */
+export declare function resolveJwtSecret(auth: Pick<AuthSection, 'jwtSecret'>): string;
+//# sourceMappingURL=jwt.d.ts.map

package/dist/jwt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jwt.d.ts","sourceRoot":"","sources":["../src/jwt.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAA;AAClD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,sBAAsB,CAAA;AAEhD,oDAAoD;AACpD,MAAM,WAAW,SAAS;IACxB,qBAAqB;IACrB,GAAG,EAAE,MAAM,CAAA;IACX,iBAAiB;IACjB,KAAK,EAAE,MAAM,CAAA;IACb,mBAAmB;IACnB,IAAI,EAAE,MAAM,CAAA;IACZ,qBAAqB;IACrB,KAAK,EAAE,IAAI,EAAE,CAAA;IACb,+BAA+B;IAC/B,GAAG,EAAE,MAAM,CAAA;IACX,gCAAgC;IAChC,GAAG,EAAE,MAAM,CAAA;CACZ;AAED,gCAAgC;AAChC,MAAM,MAAM,YAAY,GAAG;IAAE,KAAK,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,SAAS,CAAA;CAAE,GAAG;IAAE,KAAK,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAA;AAmB/F;;;;;;GAMG;AACH,wBAAgB,OAAO,CACrB,MAAM,EAAE,IAAI,CAAC,SAAS,EAAE,KAAK,GAAG,KAAK,CAAC,EACtC,MAAM,EAAE,MAAM,EACd,gBAAgB,SAAM,GACrB,MAAM,CAaR;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,YAAY,CAyCrE;AAED,uEAAuE;AACvE,wBAAgB,oBAAoB,IAAI,MAAM,CAE7C;AAED,gDAAgD;AAChD,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAEtE;AAED,0EAA0E;AAC1E,wBAAgB,iBAAiB,IAAI,MAAM,CAE1C;AAcD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,IAAI,CAAC,WAAW,EAAE,WAAW,CAAC,GAAG,MAAM,CAW7E"}