@heyramzi/utils 1.12.0 → 1.14.0

package/dist/errors/sentry/protocol.js

@@ -0,0 +1,130 @@
+export function parseDsn(dsn) {
+    const m = /^(https?):\/\/([^@/]+)@([^/]+)\/(?:.*\/)?(\d+)\/?$/.exec(dsn.trim());
+    const [, scheme, publicKey, host, projectId] = m ?? [];
+    if (!scheme || !publicKey || !host || !projectId) return null;
+    return {
+        publicKey,
+        origin: `${scheme}://${host}`,
+        projectId
+    };
+}
+function randomHex32() {
+    let out = "";
+    for(let i = 0; i < 32; i++)out += Math.floor(Math.random() * 16).toString(16);
+    return out;
+}
+const V8_FRAME = /^\s*at (?:(.+?) \()?(.+?):(\d+):(\d+)\)?\s*$/;
+export function parseStack(stack) {
+    if (!stack) return [];
+    const frames = [];
+    for (const line of stack.split("\n")){
+        const m = V8_FRAME.exec(line);
+        if (!m) continue;
+        const frame = {
+            filename: m[2],
+            lineno: Number(m[3]),
+            colno: Number(m[4])
+        };
+        if (m[1]) frame.function = m[1];
+        frames.push(frame);
+    }
+    return frames.reverse();
+}
+function describe(error) {
+    if (error instanceof Error) {
+        return {
+            type: error.name || "Error",
+            value: error.message,
+            stack: error.stack
+        };
+    }
+    if (typeof error === "string") return {
+        type: "Error",
+        value: error
+    };
+    try {
+        return {
+            type: "Error",
+            value: JSON.stringify(error)
+        };
+    } catch  {
+        return {
+            type: "Error",
+            value: String(error)
+        };
+    }
+}
+const MAX_CHAIN = 5;
+function describeChain(error) {
+    const chain = [
+        describe(error)
+    ];
+    const seen = new Set([
+        error
+    ]);
+    let next = error instanceof Error ? error.cause : undefined;
+    while(next !== undefined && next !== null && !seen.has(next) && chain.length < MAX_CHAIN){
+        seen.add(next);
+        chain.push(describe(next));
+        next = next instanceof Error ? next.cause : undefined;
+    }
+    return chain.reverse();
+}
+function cleanTags(input) {
+    const tags = {};
+    for (const [k, v] of Object.entries(input.tags ?? {})){
+        if (v !== null && v !== undefined) tags[k] = String(v);
+    }
+    if (input.surface) tags.surface = input.surface;
+    return tags;
+}
+export function buildErrorRequest(input) {
+    const dsn = parseDsn(input.dsn ?? "");
+    if (!dsn) return null;
+    const eventId = input.eventId ?? randomHex32();
+    const now = input.now ?? Date.now();
+    const values = describeChain(input.error).map(({ type, value, stack })=>{
+        const exception = {
+            type,
+            value
+        };
+        const frames = parseStack(stack);
+        if (frames.length) exception.stacktrace = {
+            frames
+        };
+        return exception;
+    });
+    const event = {
+        event_id: eventId,
+        timestamp: now / 1000,
+        platform: "javascript",
+        level: "error",
+        tags: cleanTags(input),
+        exception: {
+            values
+        }
+    };
+    if (input.release) event.release = input.release;
+    if (input.environment) event.environment = input.environment;
+    if (input.user) event.user = input.user;
+    if (input.extra) event.extra = input.extra;
+    const sentAt = new Date(now).toISOString();
+    const body = [
+        JSON.stringify({
+            event_id: eventId,
+            sent_at: sentAt,
+            dsn: input.dsn
+        }),
+        JSON.stringify({
+            type: "event"
+        }),
+        JSON.stringify(event)
+    ].join("\n");
+    return {
+        url: `${dsn.origin}/api/${dsn.projectId}/envelope/?sentry_key=${dsn.publicKey}&sentry_version=7`,
+        headers: {
+            "Content-Type": "application/x-sentry-envelope"
+        },
+        body
+    };
+}

package/dist/errors/sentry/sveltekit.js

@@ -0,0 +1,145 @@
+import { captureError } from "./index.js";
+const LOCAL_HOSTS = new Set([
+    "localhost",
+    "127.0.0.1",
+    "[::1]"
+]);
+export function shouldReport({ kind, error }) {
+    if (kind === "app") return false;
+    if (kind === "unknown") return true;
+    const status = error?.status;
+    return typeof status === "number" ? status >= 500 : true;
+}
+const STALE_CHUNK = /Failed to fetch dynamically imported module|Importing a module script failed|error loading dynamically imported module/;
+export function isStaleChunk(error) {
+    const message = error?.message;
+    return typeof message === "string" && STALE_CHUNK.test(message);
+}
+const RELOAD_KEY = "heyramzi:stale-chunk-reload";
+const RELOAD_WINDOW_MS = 30_000;
+function browserEnv() {
+    try {
+        return {
+            storage: sessionStorage,
+            now: Date.now,
+            reload: ()=>location.reload()
+        };
+    } catch  {
+        return null;
+    }
+}
+export function reloadForStaleChunk(env = browserEnv()) {
+    if (!env) return false;
+    try {
+        const last = Number(env.storage.getItem(RELOAD_KEY));
+        if (env.now() - last < RELOAD_WINDOW_MS) return false;
+        env.storage.setItem(RELOAD_KEY, String(env.now()));
+        env.reload();
+        return true;
+    } catch  {
+        return false;
+    }
+}
+function toError(raw) {
+    if (raw instanceof Error) return raw;
+    const message = raw?.message;
+    return typeof message === "string" ? new Error(message) : raw;
+}
+const STACK_LINES = 8;
+export function devErrorDetails(error) {
+    if (!(error instanceof Error)) {
+        const message = error?.message;
+        if (typeof message === "string") return {
+            message
+        };
+        try {
+            return {
+                message: typeof error === "object" ? JSON.stringify(error) : String(error)
+            };
+        } catch  {
+            return {
+                message: String(error)
+            };
+        }
+    }
+    const header = String(error);
+    const stack = error.stack?.startsWith(header) ? error.stack.slice(header.length) : error.stack;
+    const frames = stack?.split("\n").map((line)=>line.trim()).filter(Boolean).slice(0, STACK_LINES);
+    return {
+        message: error.message,
+        stack: frames?.length ? frames.join("\n") : undefined
+    };
+}
+function isLocalHost(input) {
+    return LOCAL_HOSTS.has(input.event.url.hostname);
+}
+async function report(options, input, extraTags) {
+    const { dsn, dev, release, surface, environment = "production", tags } = options;
+    if (dev || !dsn || isLocalHost(input)) return;
+    await captureError({
+        dsn,
+        error: toError(input.error),
+        surface,
+        release,
+        environment,
+        tags: {
+            ...tags,
+            ...extraTags,
+            route: input.event.route.id
+        },
+        extra: {
+            pathname: input.event.url.pathname,
+            kind: input.kind
+        }
+    });
+}
+async function respondTo(options, input) {
+    if (!options.respond) return undefined;
+    try {
+        return await options.respond(input);
+    } catch (err) {
+        console.error("[handleError] respond threw:", err);
+        return undefined;
+    }
+}
+async function answer(options, input) {
+    const body = await respondTo(options, input);
+    if (!options.dev || !shouldReport(input)) return body;
+    return {
+        ...body,
+        ...devErrorDetails(input.error)
+    };
+}
+export function createHandleClientError(options) {
+    return async (input)=>{
+        try {
+            let tags;
+            if (isStaleChunk(input.error)) {
+                if (reloadForStaleChunk()) return respondTo(options, input);
+                tags = {
+                    stale_chunk: true
+                };
+            }
+            if (shouldReport(input)) {
+                if (options.log !== false) console.error("[handleError]", input.error);
+                if (!await options.skip?.(input)) await report(options, input, tags);
+            }
+        } catch (err) {
+            console.error("[handleError] reporting failed:", err);
+        }
+        return answer(options, input);
+    };
+}
+export function createHandleServerError(options) {
+    return async (input)=>{
+        try {
+            if (shouldReport(input)) {
+                if (options.log !== false) console.error("[handleError]", toError(input.error));
+                await report(options, input);
+            }
+        } catch (err) {
+            console.error("[handleError] reporting failed:", err);
+        }
+        return answer(options, input);
+    };
+}

package/dist/format.js

@@ -0,0 +1,62 @@
+export function formatDate(date, locale = "en-US") {
+    if (!date) return "-";
+    const dateValue = typeof date === "string" && /^\d+$/.test(date) ? parseInt(date, 10) : date;
+    const parsed = new Date(dateValue);
+    if (Number.isNaN(parsed.getTime())) return "-";
+    return parsed.toLocaleDateString(locale, {
+        month: "short",
+        day: "numeric",
+        year: "numeric"
+    });
+}
+export function formatCurrency(value, currency = "USD", locale) {
+    if (!value) return "-";
+    const resolvedLocale = locale ?? (currency.toUpperCase() === "EUR" ? "fr-FR" : "en-US");
+    return new Intl.NumberFormat(resolvedLocale, {
+        style: "currency",
+        currency: currency.toUpperCase(),
+        minimumFractionDigits: 0
+    }).format(value);
+}
+export function formatAmount(cents, currency, locale = "en-US") {
+    return new Intl.NumberFormat(locale, {
+        style: "currency",
+        currency: currency.toUpperCase(),
+        minimumFractionDigits: 2
+    }).format(cents / 100);
+}
+const DEFAULT_LABELS = {
+    today: "Today",
+    yesterday: "Yesterday",
+    daysAgo: "{n} days ago",
+    weeksAgo: "{n} weeks ago",
+    monthsAgo: "{n} months ago",
+    yearsAgo: "{n} years ago",
+    weekAgo: "1 week ago",
+    monthAgo: "1 month ago",
+    yearAgo: "1 year ago"
+};
+export function formatRelativeTime(date, labels = DEFAULT_LABELS) {
+    if (!date) return "-";
+    const dateValue = typeof date === "string" && /^\d+$/.test(date) ? parseInt(date, 10) : date;
+    const parsed = new Date(dateValue);
+    if (Number.isNaN(parsed.getTime())) return "-";
+    const diffMs = Date.now() - parsed.getTime();
+    const diffDays = Math.floor(diffMs / (1000 * 60 * 60 * 24));
+    if (diffDays === 0) return labels.today;
+    if (diffDays === 1) return labels.yesterday;
+    if (diffDays < 7) return labels.daysAgo.replace("{n}", String(diffDays));
+    if (diffDays < 30) {
+        const weeks = Math.floor(diffDays / 7);
+        if (weeks === 1 && labels.weekAgo) return labels.weekAgo;
+        return labels.weeksAgo.replace("{n}", String(weeks));
+    }
+    if (diffDays < 365) {
+        const months = Math.floor(diffDays / 30);
+        if (months === 1 && labels.monthAgo) return labels.monthAgo;
+        return labels.monthsAgo.replace("{n}", String(months));
+    }
+    const years = Math.floor(diffDays / 365);
+    if (years === 1 && labels.yearAgo) return labels.yearAgo;
+    return labels.yearsAgo.replace("{n}", String(years));
+}

package/dist/grab.js

@@ -0,0 +1,112 @@
+/**
+ * Alt+Click any element in a Svelte 5 dev build to copy its HTML and component stack for a coding agent.
+ */
+
+/*
+ * Usage in +layout.svelte: if (dev) import("@heyramzi/utils/grab");
+ */
+
+/*
+ * Plain JS with no imports, so a page can also inline this file as a <script type="module">.
+ */
+
+const MAX_HTML = 400;
+
+/** @param {Element} el */
+function sourceOf(el) {
+  /** @type {Element | null} */
+  let node = el;
+  while (node && !(/** @type {any} */ (node).__svelte_meta)) node = node.parentElement;
+  return node ? /** @type {any} */ (node).__svelte_meta : null;
+}
+
+/** @param {{ file: string, line: number, column: number }} at */
+function where(at) {
+  return `${at.file}:${at.line}:${at.column}`;
+}
+
+/** @param {Element} el */
+function describe(el) {
+  // Svelte's hydration markers are <!----> comments, noise to an agent.
+  const full = el.outerHTML.replace(/<!--[^]*?-->/g, "");
+  const html = full.length > MAX_HTML ? `${full.slice(0, MAX_HTML)}…` : full;
+  const meta = sourceOf(el);
+  if (!meta) return html;
+
+  const lines = [html, `  at ${where(meta.loc)}`];
+  for (let entry = meta.parent; entry; entry = entry.parent) {
+    if (entry.type === "component") lines.push(`  in <${entry.componentTag}> at ${where(entry)}`);
+  }
+  return lines.join("\n");
+}
+
+/** @param {Element} el */
+function label(el) {
+  const meta = sourceOf(el);
+  let entry = meta?.parent;
+  while (entry && entry.type !== "component") entry = entry.parent;
+  const name = entry ? `<${entry.componentTag}>` : el.tagName.toLowerCase();
+  return meta ? `${name}  ${meta.loc.file.split("/").pop()}:${meta.loc.line}` : name;
+}
+
+function start() {
+  const box = document.createElement("div");
+  const tag = document.createElement("div");
+  box.style.cssText =
+    "position:fixed;pointer-events:none;z-index:2147483647;border:2px solid #7c3aed;background:rgb(124 58 237 / 0.08);border-radius:3px;display:none";
+  tag.style.cssText =
+    "position:absolute;left:-2px;bottom:100%;margin-bottom:4px;padding:2px 6px;font:12px/1.4 ui-monospace,monospace;color:#fff;background:#7c3aed;border-radius:3px;white-space:nowrap";
+  box.append(tag);
+  document.body.append(box);
+
+  /** @type {Element | null} */
+  let target = null;
+
+  /** @param {Element | null} el */
+  function show(el) {
+    target = el;
+    if (!el) {
+      box.style.display = "none";
+      return;
+    }
+    const r = el.getBoundingClientRect();
+    Object.assign(box.style, {
+      display: "block",
+      left: `${r.left}px`,
+      top: `${r.top}px`,
+      width: `${r.width}px`,
+      height: `${r.height}px`,
+    });
+    tag.textContent = label(el);
+  }
+
+  /** @param {MouseEvent} e */
+  function onMove(e) {
+    show(e.altKey ? document.elementFromPoint(e.clientX, e.clientY) : null);
+  }
+
+  /** @param {MouseEvent} e */
+  function onClick(e) {
+    if (!e.altKey || !target) return;
+    // Option+click on a link downloads it in Chrome, so the click is swallowed here.
+    e.preventDefault();
+    e.stopImmediatePropagation();
+    if (e.type !== "click") return;
+    navigator.clipboard.writeText(describe(target)).then(() => {
+      tag.textContent = "Copied";
+    });
+  }
+
+  addEventListener("mousemove", onMove, true);
+  addEventListener("mousedown", onClick, true);
+  addEventListener("click", onClick, true);
+  addEventListener("keyup", (e) => e.key === "Alt" && show(null), true);
+  addEventListener("blur", () => show(null));
+}
+
+const w = /** @type {any} */ (globalThis);
+if (typeof document !== "undefined" && !w.__heyramziGrab) {
+  w.__heyramziGrab = true;
+  if (document.body) start();
+  else addEventListener("DOMContentLoaded", start);
+}

package/dist/index.js

@@ -0,0 +1,10 @@
+export { cn } from "./cn.js";
+export { formatDate, formatCurrency, formatAmount, formatRelativeTime } from "./format.js";
+export { slugify, generateSlug, buildSearchParams, parseJSON, parseCommaSeparatedList, matchesQuery } from "./string.js";
+export { fetchApi } from "./error.js";
+export { isCacheExpired } from "./cache.js";
+export { Ok, Err, tryCatch, tryCatchAsync } from "./result.js";
+export { setLogger, log } from "./logger.js";
+export { debounce, throttle, sleep } from "./timing.js";
+export { clamp } from "./math.js";
+export { groupBy } from "./collection.js";

package/dist/logger.js

@@ -0,0 +1,22 @@
+let _logger = null;
+export function setLogger(logger) {
+    _logger = logger;
+}
+export function log(level, message, data) {
+    if (!_logger) return;
+    const entry = {
+        level,
+        message,
+        ...data
+    };
+    try {
+        const result = _logger.log(entry);
+        if (result instanceof Promise) {
+            result.catch((err)=>{
+                console.error("[logs] Logger failed:", err);
+            });
+        }
+    } catch (err) {
+        console.error("[logs] Logger failed:", err);
+    }
+}

package/dist/math.js

@@ -0,0 +1,3 @@
+export function clamp(value, min, max) {
+    return Math.min(Math.max(value, min), max);
+}

package/dist/og/fonts.js

@@ -0,0 +1,46 @@
+import { readFileSync } from "node:fs";
+import { tryCatch, tryCatchAsync } from "../result.js";
+const cache = new Map();
+function readRaw(path) {
+    const result = tryCatch(()=>readFileSync(path));
+    return result.ok ? result.value : null;
+}
+function toArrayBuffer(bytes) {
+    const out = new ArrayBuffer(bytes.byteLength);
+    new Uint8Array(out).set(bytes);
+    return out;
+}
+async function decodeFont(path) {
+    const cached = cache.get(path);
+    if (cached) return cached;
+    const raw = readRaw(path);
+    if (!raw) return null;
+    const isWoff2 = path.toLowerCase().endsWith(".woff2");
+    if (!isWoff2) {
+        const buf = toArrayBuffer(raw);
+        cache.set(path, buf);
+        return buf;
+    }
+    const decoded = await tryCatchAsync(async ()=>{
+        const { decompress } = await import("wawoff2");
+        return decompress(raw);
+    });
+    if (!decoded.ok) return null;
+    const buf = toArrayBuffer(decoded.value);
+    cache.set(path, buf);
+    return buf;
+}
+export async function loadFonts(configs) {
+    const decoded = [];
+    for (const config of configs){
+        const data = await decodeFont(config.path);
+        if (!data) continue;
+        decoded.push({
+            name: config.name,
+            data,
+            weight: config.weight,
+            style: config.style ?? "normal"
+        });
+    }
+    return decoded;
+}

package/dist/og/index.js

@@ -0,0 +1,3 @@
+export { renderImage, MIME_TYPES } from "./renderer.js";
+export { loadFonts } from "./fonts.js";
+export { html, raw } from "./markup.js";

package/dist/og/markup.js

@@ -0,0 +1,31 @@
+import { html as satoriHtml } from "satori-html";
+import { __unsafeHTML } from "ultrahtml";
+const RAW_MARKUP = Symbol.for("@heyramzi/marketing/imagegen/RawMarkup");
+export function raw(markup) {
+    const marked = __unsafeHTML(markup);
+    Object.defineProperty(marked, RAW_MARKUP, {
+        value: true,
+        enumerable: false
+    });
+    return marked;
+}
+export function html(strings, ...values) {
+    const flattened = values.map((value)=>{
+        if (Array.isArray(value)) {
+            const parts = value.map((item)=>{
+                if (item == null || item === false) return "";
+                if (isRawMarkup(item)) return item.value;
+                return escapeHtml(String(item));
+            });
+            return raw(parts.join(""));
+        }
+        return value;
+    });
+    return satoriHtml(strings, ...flattened);
+}
+function isRawMarkup(value) {
+    return typeof value === "object" && value !== null && RAW_MARKUP in value;
+}
+function escapeHtml(input) {
+    return input.replace(/[&<>]/g, (c)=>c === "&" ? "&amp;" : c === "<" ? "&lt;" : "&gt;");
+}

package/dist/og/renderer.js

@@ -0,0 +1,29 @@
+import satori from "satori";
+import sharp from "sharp";
+export async function renderImage(markup, options) {
+    const format = options.format ?? "png";
+    const svg = await satori(markup, {
+        width: options.size.width,
+        height: options.size.height,
+        fonts: options.fonts
+    });
+    if (format === "svg") {
+        return new TextEncoder().encode(svg);
+    }
+    const pipeline = sharp(Buffer.from(svg));
+    if (format === "avif") {
+        const buffer = await pipeline.avif({
+            quality: options.quality ?? 82
+        }).toBuffer();
+        return new Uint8Array(buffer);
+    }
+    const buffer = await pipeline.png({
+        quality: options.quality ?? 90
+    }).toBuffer();
+    return new Uint8Array(buffer);
+}
+export const MIME_TYPES = {
+    svg: "image/svg+xml",
+    png: "image/png",
+    avif: "image/avif"
+};

package/dist/result.js

@@ -0,0 +1,26 @@
+export function Ok(value) {
+    return {
+        ok: true,
+        value
+    };
+}
+export function Err(error) {
+    return {
+        ok: false,
+        error
+    };
+}
+export function tryCatch(fn) {
+    try {
+        return Ok(fn());
+    } catch (e) {
+        return Err(e instanceof Error ? e : new Error(String(e)));
+    }
+}
+export async function tryCatchAsync(fn) {
+    try {
+        return Ok(await fn());
+    } catch (e) {
+        return Err(e instanceof Error ? e : new Error(String(e)));
+    }
+}

package/dist/string.js

@@ -0,0 +1,32 @@
+export function slugify(text) {
+    return text.toLowerCase().replace(/[^\w\s-]/g, "").replace(/\s+/g, "-").replace(/-+/g, "-").trim();
+}
+export function generateSlug(text) {
+    return text.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
+}
+export function buildSearchParams(params) {
+    const entries = Object.entries(params).filter((entry)=>entry[1] !== undefined);
+    if (entries.length === 0) return "";
+    return `?${entries.map(([k, v])=>`${k}=${encodeURIComponent(v)}`).join("&")}`;
+}
+export function parseJSON(raw) {
+    if (!raw) return undefined;
+    try {
+        return JSON.parse(raw);
+    } catch  {
+        return undefined;
+    }
+}
+export function parseCommaSeparatedList(text) {
+    if (!text) return [];
+    return text.split(",").map((s)=>s.trim()).filter(Boolean);
+}
+function foldForSearch(text) {
+    return text.normalize("NFD").replace(/\p{Diacritic}/gu, "").toLowerCase();
+}
+export function matchesQuery(haystack, query) {
+    const words = foldForSearch(query).split(/\s+/).filter(Boolean);
+    if (words.length === 0) return true;
+    const target = foldForSearch(haystack);
+    return words.every((word)=>target.includes(word));
+}

package/dist/testimonials/render-content.js

@@ -0,0 +1,15 @@
+const HTML_ESCAPES = {
+    "&": "&",
+    "<": "&lt;",
+    ">": "&gt;",
+    '"': "&quot;",
+    "'": "&#39;"
+};
+function escapeHtml(input) {
+    return input.replace(/[&<>"']/g, (ch)=>HTML_ESCAPES[ch] ?? ch);
+}
+export function renderTestimonialContent(content) {
+    if (!content) return "";
+    const escaped = escapeHtml(content);
+    return escaped.replace(/\*\*([^*]+?)\*\*/g, "<strong>$1</strong>");
+}