@htmless/core 0.1.0

package/dist/integrations/sheets.d.ts

@@ -0,0 +1,41 @@
+export interface ParsedSheetUrl {
+    spreadsheetId: string;
+    gid?: string;
+}
+export interface SheetToEntriesResult {
+    entries: Record<string, unknown>[];
+    unmappedColumns: string[];
+    headers: string[];
+}
+/**
+ * Extract spreadsheet ID and optional GID from a Google Sheets URL.
+ * Accepts standard share links, /edit links, and /pub links.
+ */
+export declare function parseSheetUrl(url: string): ParsedSheetUrl;
+/**
+ * Convert a Google Sheets URL into its public CSV-export URL.
+ */
+export declare function buildCsvExportUrl(url: string): string;
+/**
+ * Fetch sheet contents as raw CSV text via the public export endpoint.
+ */
+export declare function fetchSheetAsCsv(url: string): Promise<string>;
+/**
+ * Convert parsed CSV data into entry objects.
+ *
+ * @param csv           Raw CSV string
+ * @param contentTypeKey  Used for context in the result (not embedded in entries)
+ * @param fieldMapping  Optional override: column header → field key
+ */
+export declare function sheetToEntries(csv: string, _contentTypeKey: string, fieldMapping?: Record<string, string>): SheetToEntriesResult;
+export interface InferredSheetField {
+    key: string;
+    name: string;
+    type: string;
+    samples: unknown[];
+}
+/**
+ * Analyze CSV data and infer field types for schema generation.
+ */
+export declare function inferFieldsFromCsv(csv: string): InferredSheetField[];
+//# sourceMappingURL=sheets.d.ts.map

package/dist/integrations/sheets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sheets.d.ts","sourceRoot":"","sources":["../../src/integrations/sheets.ts"],"names":[],"mappings":"AAOA,MAAM,WAAW,cAAc;IAC7B,aAAa,EAAE,MAAM,CAAC;IACtB,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC;IACnC,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAID;;;GAGG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,cAAc,CAgBzD;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAIrD;AAED;;GAEG;AACH,wBAAsB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAelE;AA0DD;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,GAAG,EAAE,MAAM,EACX,eAAe,EAAE,MAAM,EACvB,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GACpC,oBAAoB,CA0DtB;AA0BD,MAAM,WAAW,kBAAkB;IACjC,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,OAAO,EAAE,CAAC;CACpB;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,kBAAkB,EAAE,CAmBpE"}

package/dist/integrations/sheets.js

@@ -0,0 +1,230 @@
+// ─── Google Sheets → CMS Integration ───
+//
+// Works with the public CSV-export URL — no Google API key required.
+// Users publish their sheet, paste the URL, and we turn rows into entries.
+// ─── URL parsing ───────────────────────────────────────────────────────
+/**
+ * Extract spreadsheet ID and optional GID from a Google Sheets URL.
+ * Accepts standard share links, /edit links, and /pub links.
+ */
+export function parseSheetUrl(url) {
+    // Match the spreadsheet ID from various URL formats
+    const idMatch = url.match(/\/spreadsheets\/d\/([a-zA-Z0-9_-]+)/);
+    if (!idMatch) {
+        throw new Error('Invalid Google Sheets URL — could not extract spreadsheet ID');
+    }
+    const spreadsheetId = idMatch[1];
+    // Try to extract GID from hash or query param
+    const gidMatch = url.match(/[#&?]gid=(\d+)/);
+    const gid = gidMatch ? gidMatch[1] : undefined;
+    return { spreadsheetId, gid };
+}
+/**
+ * Convert a Google Sheets URL into its public CSV-export URL.
+ */
+export function buildCsvExportUrl(url) {
+    const { spreadsheetId, gid } = parseSheetUrl(url);
+    const base = `https://docs.google.com/spreadsheets/d/${spreadsheetId}/export?format=csv`;
+    return gid ? `${base}&gid=${gid}` : base;
+}
+/**
+ * Fetch sheet contents as raw CSV text via the public export endpoint.
+ */
+export async function fetchSheetAsCsv(url) {
+    const csvUrl = buildCsvExportUrl(url);
+    const response = await fetch(csvUrl, {
+        headers: { Accept: 'text/csv' },
+        redirect: 'follow',
+    });
+    if (!response.ok) {
+        throw new Error(`Failed to fetch sheet (HTTP ${response.status}). Make sure the sheet is published to the web.`);
+    }
+    return response.text();
+}
+// ─── CSV parsing (lightweight, no dependency) ──────────────────────────
+function parseCsvLine(line) {
+    const fields = [];
+    let current = '';
+    let inQuotes = false;
+    for (let i = 0; i < line.length; i++) {
+        const ch = line[i];
+        if (inQuotes) {
+            if (ch === '"') {
+                // Check for escaped quote
+                if (i + 1 < line.length && line[i + 1] === '"') {
+                    current += '"';
+                    i++; // skip the second quote
+                }
+                else {
+                    inQuotes = false;
+                }
+            }
+            else {
+                current += ch;
+            }
+        }
+        else {
+            if (ch === '"') {
+                inQuotes = true;
+            }
+            else if (ch === ',') {
+                fields.push(current.trim());
+                current = '';
+            }
+            else {
+                current += ch;
+            }
+        }
+    }
+    fields.push(current.trim());
+    return fields;
+}
+function parseCsv(csv) {
+    const lines = csv.split(/\r?\n/).filter((line) => line.trim().length > 0);
+    return lines.map(parseCsvLine);
+}
+// ─── Column header → field key mapping ─────────────────────────────────
+function headerToCamelCase(header) {
+    return header
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+(.)/g, (_, c) => c.toUpperCase())
+        .replace(/^[^a-z]/, (c) => c.toLowerCase())
+        .replace(/[^a-zA-Z0-9]/g, '');
+}
+// ─── Sheet → Entries ───────────────────────────────────────────────────
+/**
+ * Convert parsed CSV data into entry objects.
+ *
+ * @param csv           Raw CSV string
+ * @param contentTypeKey  Used for context in the result (not embedded in entries)
+ * @param fieldMapping  Optional override: column header → field key
+ */
+export function sheetToEntries(csv, _contentTypeKey, fieldMapping) {
+    const rows = parseCsv(csv);
+    if (rows.length < 2) {
+        return { entries: [], unmappedColumns: [], headers: [] };
+    }
+    const headers = rows[0];
+    const dataRows = rows.slice(1);
+    // Build mapping: column index → field key
+    const mapping = headers.map((header) => {
+        if (fieldMapping && fieldMapping[header]) {
+            return fieldMapping[header];
+        }
+        const camel = headerToCamelCase(header);
+        return camel || null;
+    });
+    // Track unmapped columns
+    const unmappedColumns = [];
+    headers.forEach((header, idx) => {
+        if (mapping[idx] === null) {
+            unmappedColumns.push(header);
+        }
+    });
+    // Convert rows to entry objects
+    const entries = [];
+    for (const row of dataRows) {
+        const entry = {};
+        let hasData = false;
+        for (let i = 0; i < headers.length; i++) {
+            const fieldKey = mapping[i];
+            if (!fieldKey)
+                continue;
+            const rawValue = row[i] ?? '';
+            // Basic type coercion
+            const value = coerceValue(rawValue);
+            if (value !== '' && value !== null) {
+                hasData = true;
+            }
+            entry[fieldKey] = value;
+        }
+        if (hasData) {
+            entries.push(entry);
+        }
+    }
+    return {
+        entries,
+        unmappedColumns,
+        headers,
+    };
+}
+// ─── Value coercion ────────────────────────────────────────────────────
+function coerceValue(raw) {
+    if (raw === '')
+        return '';
+    // Boolean
+    if (raw.toLowerCase() === 'true')
+        return true;
+    if (raw.toLowerCase() === 'false')
+        return false;
+    // Number
+    const num = Number(raw);
+    if (!isNaN(num) && raw.trim() !== '')
+        return num;
+    // ISO date
+    if (/^\d{4}-\d{2}-\d{2}/.test(raw)) {
+        const d = new Date(raw);
+        if (!isNaN(d.getTime()))
+            return d.toISOString();
+    }
+    return raw;
+}
+/**
+ * Analyze CSV data and infer field types for schema generation.
+ */
+export function inferFieldsFromCsv(csv) {
+    const rows = parseCsv(csv);
+    if (rows.length < 2)
+        return [];
+    const headers = rows[0];
+    const dataRows = rows.slice(1, 11); // sample first 10
+    return headers.map((header, colIdx) => {
+        const key = headerToCamelCase(header);
+        const samples = dataRows.map((row) => coerceValue(row[colIdx] ?? ''));
+        const type = inferColumnType(samples);
+        return {
+            key: key || header.toLowerCase().replace(/\s+/g, '_'),
+            name: header.trim(),
+            type,
+            samples: samples.slice(0, 3),
+        };
+    });
+}
+function inferColumnType(samples) {
+    const types = samples
+        .filter((s) => s !== '' && s !== null && s !== undefined)
+        .map((s) => {
+        if (typeof s === 'boolean')
+            return 'boolean';
+        if (typeof s === 'number')
+            return 'number';
+        if (typeof s === 'string') {
+            if (/^\d{4}-\d{2}-\d{2}T/.test(s))
+                return 'date';
+            if (/^https?:\/\//i.test(s) && /\.(jpe?g|png|gif|webp|svg)/i.test(s))
+                return 'media';
+            if (s.length > 500)
+                return 'richtext';
+            return 'text';
+        }
+        return 'text';
+    });
+    if (types.length === 0)
+        return 'text';
+    // Majority vote
+    const counts = new Map();
+    for (const t of types) {
+        counts.set(t, (counts.get(t) ?? 0) + 1);
+    }
+    let best = 'text';
+    let bestCount = 0;
+    for (const [t, c] of counts) {
+        if (c > bestCount) {
+            best = t;
+            bestCount = c;
+        }
+    }
+    return best;
+}
+//# sourceMappingURL=sheets.js.map

package/dist/integrations/sheets.js.map

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

package/dist/media/metadata.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Extract basic metadata (dimensions) from an image buffer without any
+ * external dependencies.  Supports PNG and JPEG header parsing.
+ */
+export declare function extractMetadata(buffer: Buffer, mimeType: string): Promise<{
+    width?: number;
+    height?: number;
+}>;
+//# sourceMappingURL=metadata.d.ts.map

package/dist/media/metadata.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metadata.d.ts","sourceRoot":"","sources":["../../src/media/metadata.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,wBAAsB,eAAe,CACnC,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAe9C"}

package/dist/media/metadata.js

@@ -0,0 +1,84 @@
+/**
+ * Extract basic metadata (dimensions) from an image buffer without any
+ * external dependencies.  Supports PNG and JPEG header parsing.
+ */
+export async function extractMetadata(buffer, mimeType) {
+    if (mimeType === 'image/png') {
+        return parsePngDimensions(buffer);
+    }
+    if (mimeType === 'image/jpeg' || mimeType === 'image/jpg') {
+        return parseJpegDimensions(buffer);
+    }
+    if (mimeType === 'image/gif') {
+        return parseGifDimensions(buffer);
+    }
+    // Non-image or unsupported format
+    return {};
+}
+// ─── PNG ────────────────────────────────────────────────────────────
+// PNG IHDR chunk starts at byte 16. Width at offset 16 (4 bytes BE),
+// height at offset 20 (4 bytes BE).
+function parsePngDimensions(buf) {
+    // Minimum valid PNG is ~33 bytes (signature + IHDR)
+    if (buf.length < 24)
+        return {};
+    // Check PNG signature: 89 50 4E 47 0D 0A 1A 0A
+    if (buf[0] !== 0x89 ||
+        buf[1] !== 0x50 ||
+        buf[2] !== 0x4e ||
+        buf[3] !== 0x47) {
+        return {};
+    }
+    const width = buf.readUInt32BE(16);
+    const height = buf.readUInt32BE(20);
+    return { width, height };
+}
+// ─── JPEG ───────────────────────────────────────────────────────────
+// Walk SOF markers to find frame dimensions.
+function parseJpegDimensions(buf) {
+    if (buf.length < 4)
+        return {};
+    // Check JPEG SOI marker: FF D8
+    if (buf[0] !== 0xff || buf[1] !== 0xd8)
+        return {};
+    let offset = 2;
+    while (offset < buf.length - 1) {
+        // Find next marker
+        if (buf[offset] !== 0xff) {
+            offset++;
+            continue;
+        }
+        const marker = buf[offset + 1];
+        // SOF markers (SOF0 through SOF15, except SOF4/DHT and SOF12/DAC)
+        if ((marker >= 0xc0 && marker <= 0xc3) ||
+            (marker >= 0xc5 && marker <= 0xc7) ||
+            (marker >= 0xc9 && marker <= 0xcb) ||
+            (marker >= 0xcd && marker <= 0xcf)) {
+            if (offset + 9 > buf.length)
+                return {};
+            const height = buf.readUInt16BE(offset + 5);
+            const width = buf.readUInt16BE(offset + 7);
+            return { width, height };
+        }
+        // Skip to next marker — segment length is at offset+2 (2 bytes BE)
+        if (offset + 3 >= buf.length)
+            return {};
+        const segmentLength = buf.readUInt16BE(offset + 2);
+        offset += 2 + segmentLength;
+    }
+    return {};
+}
+// ─── GIF ────────────────────────────────────────────────────────────
+// Width at byte 6 (LE uint16), height at byte 8 (LE uint16).
+function parseGifDimensions(buf) {
+    if (buf.length < 10)
+        return {};
+    // Check GIF signature
+    const sig = buf.subarray(0, 3).toString('ascii');
+    if (sig !== 'GIF')
+        return {};
+    const width = buf.readUInt16LE(6);
+    const height = buf.readUInt16LE(8);
+    return { width, height };
+}
+//# sourceMappingURL=metadata.js.map

package/dist/media/metadata.js.map

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

package/dist/media/presets.d.ts

@@ -0,0 +1,17 @@
+export interface ImagePreset {
+    name: string;
+    w: number;
+    h: number;
+    fit: string;
+    fm: string;
+    q: number;
+}
+/**
+ * Get a built-in image preset by name.
+ */
+export declare function getPreset(name: string): ImagePreset | undefined;
+/**
+ * Get all built-in presets.
+ */
+export declare function getAllPresets(): ImagePreset[];
+//# sourceMappingURL=presets.d.ts.map

package/dist/media/presets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"presets.d.ts","sourceRoot":"","sources":["../../src/media/presets.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,GAAG,EAAE,MAAM,CAAC;IACZ,EAAE,EAAE,MAAM,CAAC;IACX,CAAC,EAAE,MAAM,CAAC;CACX;AAUD;;GAEG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CAE/D;AAED;;GAEG;AACH,wBAAgB,aAAa,IAAI,WAAW,EAAE,CAE7C"}

package/dist/media/presets.js

@@ -0,0 +1,21 @@
+// ─── Image Presets ───────────────────────────────────────────────────
+const BUILT_IN_PRESETS = [
+    { name: 'thumbnail', w: 150, h: 150, fit: 'cover', fm: 'webp', q: 80 },
+    { name: 'small', w: 400, h: 300, fit: 'cover', fm: 'webp', q: 80 },
+    { name: 'medium', w: 800, h: 600, fit: 'cover', fm: 'webp', q: 80 },
+    { name: 'large', w: 1200, h: 900, fit: 'cover', fm: 'webp', q: 80 },
+    { name: 'hero', w: 1920, h: 1080, fit: 'cover', fm: 'webp', q: 85 },
+];
+/**
+ * Get a built-in image preset by name.
+ */
+export function getPreset(name) {
+    return BUILT_IN_PRESETS.find((p) => p.name === name);
+}
+/**
+ * Get all built-in presets.
+ */
+export function getAllPresets() {
+    return [...BUILT_IN_PRESETS];
+}
+//# sourceMappingURL=presets.js.map

package/dist/media/presets.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"presets.js","sourceRoot":"","sources":["../../src/media/presets.ts"],"names":[],"mappings":"AAAA,wEAAwE;AAWxE,MAAM,gBAAgB,GAAkB;IACtC,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC,EAAE,GAAG,EAAG,CAAC,EAAE,GAAG,EAAG,GAAG,EAAE,OAAO,EAAE,EAAE,EAAE,MAAM,EAAE,CAAC,EAAE,EAAE,EAAE;IACxE,EAAE,IAAI,EAAE,OAAO,EAAM,CAAC,EAAE,GAAG,EAAG,CAAC,EAAE,GAAG,EAAG,GAAG,EAAE,OAAO,EAAE,EAAE,EAAE,MAAM,EAAE,CAAC,EAAE,EAAE,EAAE;IACxE,EAAE,IAAI,EAAE,QAAQ,EAAK,CAAC,EAAE,GAAG,EAAG,CAAC,EAAE,GAAG,EAAG,GAAG,EAAE,OAAO,EAAE,EAAE,EAAE,MAAM,EAAE,CAAC,EAAE,EAAE,EAAE;IACxE,EAAE,IAAI,EAAE,OAAO,EAAM,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,GAAG,EAAG,GAAG,EAAE,OAAO,EAAE,EAAE,EAAE,MAAM,EAAE,CAAC,EAAE,EAAE,EAAE;IACxE,EAAE,IAAI,EAAE,MAAM,EAAO,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,EAAE,GAAG,EAAE,OAAO,EAAE,EAAE,EAAE,MAAM,EAAE,CAAC,EAAE,EAAE,EAAE;CACzE,CAAC;AAEF;;GAEG;AACH,MAAM,UAAU,SAAS,CAAC,IAAY;IACpC,OAAO,gBAAgB,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC;AACvD,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,aAAa;IAC3B,OAAO,CAAC,GAAG,gBAAgB,CAAC,CAAC;AAC/B,CAAC"}

package/dist/media/storage.d.ts

@@ -0,0 +1,16 @@
+export interface StorageProvider {
+    upload(key: string, buffer: Buffer, mimeType: string): Promise<void>;
+    delete(key: string): Promise<void>;
+    getUrl(key: string): string;
+}
+export declare class LocalStorageProvider implements StorageProvider {
+    private readonly baseDir;
+    constructor(baseDir?: string);
+    upload(key: string, buffer: Buffer, _mimeType: string): Promise<void>;
+    delete(key: string): Promise<void>;
+    getUrl(key: string): string;
+    /** Resolve a storage key to an absolute path on disk. */
+    resolve(key: string): string;
+}
+export declare function getStorageProvider(): StorageProvider;
+//# sourceMappingURL=storage.d.ts.map

package/dist/media/storage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../../src/media/storage.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,eAAe;IAC9B,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACrE,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnC,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;CAC7B;AAID,qBAAa,oBAAqB,YAAW,eAAe;IAC1D,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;gBAErB,OAAO,SAAc;IAI3B,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAWrE,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQxC,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM;IAI3B,yDAAyD;IACzD,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM;CAG7B;AAMD,wBAAgB,kBAAkB,IAAI,eAAe,CAKpD"}

package/dist/media/storage.js

@@ -0,0 +1,39 @@
+import { mkdirSync, existsSync, writeFileSync, unlinkSync } from 'fs';
+import { join, dirname } from 'path';
+// ─── Local filesystem provider ──────────────────────────────────────
+export class LocalStorageProvider {
+    baseDir;
+    constructor(baseDir = './uploads') {
+        this.baseDir = baseDir;
+    }
+    async upload(key, buffer, _mimeType) {
+        const filePath = join(this.baseDir, key);
+        const dir = dirname(filePath);
+        if (!existsSync(dir)) {
+            mkdirSync(dir, { recursive: true });
+        }
+        writeFileSync(filePath, buffer);
+    }
+    async delete(key) {
+        const filePath = join(this.baseDir, key);
+        if (existsSync(filePath)) {
+            unlinkSync(filePath);
+        }
+    }
+    getUrl(key) {
+        return `/cda/v1/media/${key}`;
+    }
+    /** Resolve a storage key to an absolute path on disk. */
+    resolve(key) {
+        return join(this.baseDir, key);
+    }
+}
+// ─── Factory ────────────────────────────────────────────────────────
+let _provider;
+export function getStorageProvider() {
+    if (!_provider) {
+        _provider = new LocalStorageProvider();
+    }
+    return _provider;
+}
+//# sourceMappingURL=storage.js.map

package/dist/media/storage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.js","sourceRoot":"","sources":["../../src/media/storage.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,aAAa,EAAgB,UAAU,EAAE,MAAM,IAAI,CAAC;AACpF,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AAUrC,uEAAuE;AAEvE,MAAM,OAAO,oBAAoB;IACd,OAAO,CAAS;IAEjC,YAAY,OAAO,GAAG,WAAW;QAC/B,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACzB,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,GAAW,EAAE,MAAc,EAAE,SAAiB;QACzD,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;QACzC,MAAM,GAAG,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;QAE9B,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;YACrB,SAAS,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QACtC,CAAC;QAED,aAAa,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IAClC,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,GAAW;QACtB,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;QAEzC,IAAI,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;YACzB,UAAU,CAAC,QAAQ,CAAC,CAAC;QACvB,CAAC;IACH,CAAC;IAED,MAAM,CAAC,GAAW;QAChB,OAAO,iBAAiB,GAAG,EAAE,CAAC;IAChC,CAAC;IAED,yDAAyD;IACzD,OAAO,CAAC,GAAW;QACjB,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;IACjC,CAAC;CACF;AAED,uEAAuE;AAEvE,IAAI,SAAsC,CAAC;AAE3C,MAAM,UAAU,kBAAkB;IAChC,IAAI,CAAC,SAAS,EAAE,CAAC;QACf,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IACzC,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/dist/media/transforms-engine.d.ts

@@ -0,0 +1,46 @@
+export interface FocalPoint {
+    /** Horizontal focal point, 0-1 range (0 = left, 1 = right) */
+    fp_x: number;
+    /** Vertical focal point, 0-1 range (0 = top, 1 = bottom) */
+    fp_y: number;
+}
+export interface TransformParams {
+    /** Target width in pixels */
+    w?: number;
+    /** Target height in pixels */
+    h?: number;
+    /** Resize fit mode: cover, contain, fill, inside, outside */
+    fit?: string;
+    /** Output format: jpeg, png, webp, avif, gif */
+    fm?: string;
+    /** Quality (1-100) */
+    q?: number;
+    /** Focal point X (0-1) */
+    fp_x?: number;
+    /** Focal point Y (0-1) */
+    fp_y?: number;
+}
+export interface TransformResult {
+    buffer: Buffer;
+    /** Headers describing which transforms were requested (for pass-through mode) */
+    headers: Record<string, string>;
+}
+/**
+ * Transform an image buffer according to the given params.
+ *
+ * Currently a pass-through: returns the original buffer unchanged and
+ * records the requested transforms in `headers`. Once sharp is added as
+ * a dependency, this function will perform actual resize/format/quality
+ * operations.
+ */
+export declare function transformImage(buffer: Buffer, params: TransformParams): Promise<Buffer>;
+/**
+ * Build response headers describing the transforms that were applied
+ * (or requested in pass-through mode).
+ */
+export declare function buildTransformHeaders(params: TransformParams): Record<string, string>;
+/**
+ * Parse transform query params from a request query object.
+ */
+export declare function parseTransformParams(query: Record<string, string | undefined>): TransformParams;
+//# sourceMappingURL=transforms-engine.d.ts.map

package/dist/media/transforms-engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transforms-engine.d.ts","sourceRoot":"","sources":["../../src/media/transforms-engine.ts"],"names":[],"mappings":"AAOA,MAAM,WAAW,UAAU;IACzB,8DAA8D;IAC9D,IAAI,EAAE,MAAM,CAAC;IACb,4DAA4D;IAC5D,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,eAAe;IAC9B,6BAA6B;IAC7B,CAAC,CAAC,EAAE,MAAM,CAAC;IACX,8BAA8B;IAC9B,CAAC,CAAC,EAAE,MAAM,CAAC;IACX,6DAA6D;IAC7D,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,gDAAgD;IAChD,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,sBAAsB;IACtB,CAAC,CAAC,EAAE,MAAM,CAAC;IACX,0BAA0B;IAC1B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,0BAA0B;IAC1B,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,iFAAiF;IACjF,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACjC;AAKD;;;;;;;GAOG;AACH,wBAAsB,cAAc,CAClC,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,eAAe,GACtB,OAAO,CAAC,MAAM,CAAC,CAgCjB;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAYrF;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,GACxC,eAAe,CAYjB"}

package/dist/media/transforms-engine.js

@@ -0,0 +1,91 @@
+// ─── Image Transform Engine ──────────────────────────────────────────
+//
+// Provides a transform pipeline for image buffers. Currently a
+// pass-through implementation that records requested transforms in
+// response headers. Actual pixel manipulation (resize, format
+// conversion) requires sharp/libvips which will be added later.
+const VALID_FITS = ['cover', 'contain', 'fill', 'inside', 'outside'];
+const VALID_FORMATS = ['jpeg', 'png', 'webp', 'avif', 'gif'];
+/**
+ * Transform an image buffer according to the given params.
+ *
+ * Currently a pass-through: returns the original buffer unchanged and
+ * records the requested transforms in `headers`. Once sharp is added as
+ * a dependency, this function will perform actual resize/format/quality
+ * operations.
+ */
+export async function transformImage(buffer, params) {
+    // Validate params
+    if (params.w !== undefined && (params.w < 1 || params.w > 8192)) {
+        throw new Error('Width must be between 1 and 8192');
+    }
+    if (params.h !== undefined && (params.h < 1 || params.h > 8192)) {
+        throw new Error('Height must be between 1 and 8192');
+    }
+    if (params.fit !== undefined && !VALID_FITS.includes(params.fit)) {
+        throw new Error(`Invalid fit mode: ${params.fit}. Must be one of: ${VALID_FITS.join(', ')}`);
+    }
+    if (params.fm !== undefined && !VALID_FORMATS.includes(params.fm)) {
+        throw new Error(`Invalid format: ${params.fm}. Must be one of: ${VALID_FORMATS.join(', ')}`);
+    }
+    if (params.q !== undefined && (params.q < 1 || params.q > 100)) {
+        throw new Error('Quality must be between 1 and 100');
+    }
+    if (params.fp_x !== undefined && (params.fp_x < 0 || params.fp_x > 1)) {
+        throw new Error('Focal point X must be between 0 and 1');
+    }
+    if (params.fp_y !== undefined && (params.fp_y < 0 || params.fp_y > 1)) {
+        throw new Error('Focal point Y must be between 0 and 1');
+    }
+    // Pass-through: return original buffer.
+    // In the future, sharp-based transforms will go here:
+    //   const img = sharp(buffer);
+    //   if (params.w || params.h) img.resize(params.w, params.h, { fit, position });
+    //   if (params.fm) img.toFormat(params.fm, { quality: params.q });
+    //   return img.toBuffer();
+    return buffer;
+}
+/**
+ * Build response headers describing the transforms that were applied
+ * (or requested in pass-through mode).
+ */
+export function buildTransformHeaders(params) {
+    const headers = {};
+    if (params.w !== undefined)
+        headers['X-Transform-Width'] = String(params.w);
+    if (params.h !== undefined)
+        headers['X-Transform-Height'] = String(params.h);
+    if (params.fit)
+        headers['X-Transform-Fit'] = params.fit;
+    if (params.fm)
+        headers['X-Transform-Format'] = params.fm;
+    if (params.q !== undefined)
+        headers['X-Transform-Quality'] = String(params.q);
+    if (params.fp_x !== undefined)
+        headers['X-Transform-FP-X'] = String(params.fp_x);
+    if (params.fp_y !== undefined)
+        headers['X-Transform-FP-Y'] = String(params.fp_y);
+    return headers;
+}
+/**
+ * Parse transform query params from a request query object.
+ */
+export function parseTransformParams(query) {
+    const params = {};
+    if (query.w)
+        params.w = parseInt(query.w, 10);
+    if (query.h)
+        params.h = parseInt(query.h, 10);
+    if (query.fit)
+        params.fit = query.fit;
+    if (query.fm)
+        params.fm = query.fm;
+    if (query.q)
+        params.q = parseInt(query.q, 10);
+    if (query.fp_x)
+        params.fp_x = parseFloat(query.fp_x);
+    if (query.fp_y)
+        params.fp_y = parseFloat(query.fp_y);
+    return params;
+}
+//# sourceMappingURL=transforms-engine.js.map