@heyramzi/utils 0.0.0-stage → 1.13.0

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>");
+}

package/dist/testimonials/server.js

@@ -0,0 +1,21 @@
+export const DEFAULT_TESTIMONIALS_BASE_URL = "https://app.upsys-consulting.com";
+export async function fetchPublicTestimonialCollection(token, opts = {}) {
+    const fetchImpl = opts.fetchImpl ?? globalThis.fetch;
+    const baseUrl = (opts.baseUrl ?? DEFAULT_TESTIMONIALS_BASE_URL).replace(/\/$/, "");
+    const params = new URLSearchParams();
+    if (opts.locale) params.set("locale", opts.locale);
+    if (opts.layout) params.set("layout", opts.layout);
+    const query = params.toString();
+    const url = `${baseUrl}/api/testimonials/public/${encodeURIComponent(token)}${query ? `?${query}` : ""}`;
+    const response = await fetchImpl(url);
+    if (!response.ok) return null;
+    return await response.json();
+}
+export async function fetchPublicTestimonials(token, opts = {}) {
+    const data = await fetchPublicTestimonialCollection(token, opts);
+    return data?.testimonials ?? [];
+}
+export async function fetchPublicTestimonialStats(token, opts = {}) {
+    const data = await fetchPublicTestimonialCollection(token, opts);
+    return data?.collection.stats ?? [];
+}

package/dist/timing.js

@@ -0,0 +1,20 @@
+export function debounce(fn, delay) {
+    let timeoutId;
+    return (...args)=>{
+        clearTimeout(timeoutId);
+        timeoutId = setTimeout(()=>fn(...args), delay);
+    };
+}
+export function throttle(fn, limit) {
+    let inThrottle = false;
+    return (...args)=>{
+        if (!inThrottle) {
+            fn(...args);
+            inThrottle = true;
+            setTimeout(()=>inThrottle = false, limit);
+        }
+    };
+}
+export function sleep(ms) {
+    return new Promise((resolve)=>setTimeout(resolve, ms));
+}

package/dist/vite.js

@@ -0,0 +1,265 @@
+import { execFileSync } from "node:child_process";
+import net from "node:net";
+
+/** Let dependencies resolve their own package imports instead of Kit's app aliases. */
+export function packageImportsOverKitAlias() {
+  return {
+    name: "package-imports-over-kit-alias",
+    config(config) {
+      const alias = config.resolve?.alias;
+      if (!config.resolve || !Array.isArray(alias)) return;
+      config.resolve.alias = alias.filter(
+        (entry) => !/^\^#(src|scripts)\\?\//.test(String(entry.find).slice(1)),
+      );
+    },
+  };
+}
+
+/** Both loopback stacks: a dev server may be bound to only one of them. */
+const HOSTS = ["127.0.0.1", "::1"];
+
+/**
+ * Vite plugin: before the dev server binds, kill whatever is already listening on the configured port and take the port back.
+ */
+
+/*
+ * Without this, Vite silently increments to the next free port when the configured one is busy (e.g. a stale dev server left running),
+ */
+
+/*
+ * so you end up on 3161/3162 instead of the 3160 you asked for. This plugin reclaims the intended port instead of drifting.
+ */
+
+/*
+ * It reclaims a port from a listener that has stopped answering.
+ */
+
+/*
+ * It never takes one from a dev server that is still serving: that server belongs to somebody, and on this machine "somebody" is routinely a second agent session working in
+ */
+
+/*
+ * the same repo. A dedicated port range per project makes the owner predictable, not disposable. Pass `RECLAIM_PORT_FORCE=1` to take the port from a live server anyway.
+ */
+
+/*
+ * Reads `server.port` from the resolved config, so it works whether the port is set in `vite.config.ts` or passed as `--port` on the CLI.
+ */
+
+/*
+ * Dev-only and macOS/Linux only (uses `lsof`). On Windows or any failure it is a no-op and Vite falls back to its default behaviour.
+ */
+
+/*
+ * WHY `apply: "serve"` is not enough on its own: Vitest and `vite preview` both resolve the same config in serve mode without ever binding `server.port`,
+ */
+
+/*
+ * so either one used to reach this hook, find the running dev server on that port and SIGTERM it.
+ */
+
+/*
+ * The developer sees their dev terminal exit 143 with no explanation, which reads as the machine dying on its own.
+ */
+
+/*
+ * Anything that does not bind the port must never reclaim it.
+ */
+
+/*
+ * WHY this is plain JS (not vite.ts): vite.config.ts is read by config loaders (vp / native node strip-types) that refuse to type-strip a `.ts` file under
+ */
+
+/*
+ * node_modules. Shipping the entry as JS + a `.d.ts` lets every consumer load it from their config regardless of loader. Types live in vite.d.ts.
+ */
+
+/*
+ * Usage in vite.config.ts: import { reclaimPort } from "@heyramzi/utils/vite"; plugins: [reclaimPort(), ...]
+ */
+export function reclaimPort() {
+  // WHY a closure: `isPreview` rides on the ConfigEnv the `config` hook is
+  // handed, and never reaches the resolved config, so `configResolved` alone
+  // cannot tell `vite preview` from `vite dev`.
+  let isPreview = false;
+
+  return {
+    name: "reclaim-port",
+    apply: "serve",
+    enforce: "pre",
+    config(_userConfig, env) {
+      isPreview = Boolean(env?.isPreview);
+    },
+    async configResolved(config) {
+      if (isPreview || isNotBindingTheDevPort(config)) return;
+
+      const port = config.server.port;
+      if (!port || process.platform === "win32") return;
+
+      // WHY the self/parent filter: a `vite.config.ts` edit restarts the dev server inside the SAME process, and the old server still holds the port at that moment.
+
+      // Without this the plugin SIGTERMs its own pid and the developer's dev server dies on a config save.
+      const pids = listenerPids(port).filter((pid) => pid !== process.pid && pid !== process.ppid);
+      if (pids.length === 0) return;
+
+      // WHY liveness is tested and not assumed: this plugin was written for a stale server, and "stale" was never checked.
+
+      // It killed whatever held the port, so a second terminal, a second worktree or a second agent session running `pnpm dev` SIGTERMed a colleague's working server and that terminal died
+
+      // on `Exit status 143` with nothing to read. A port that still answers has an owner; only a port that has stopped answering is abandoned.
+      if (!isForced() && (await isServing(port))) {
+        throw new Error(
+          `[reclaim-port] Port ${port} is already serving (pid ${pids.join(", ")}).\n` +
+            `Another dev server is live on it, so this one will not take it.\n` +
+            `Use the server that is already running at http://localhost:${port},\n` +
+            `or stop it first. To take the port from a live server anyway, set ` +
+            `RECLAIM_PORT_FORCE=1.`,
+        );
+      }
+
+      config.logger.info(
+        `[reclaim-port] port ${port} held by an unresponsive listener, reclaiming (killing ${pids.join(", ")})`,
+      );
+      for (const pid of pids) {
+        try {
+          process.kill(pid, "SIGTERM");
+        } catch {
+          // already gone, or not ours to kill -- ignore and let the wait below decide
+        }
+      }
+      await waitForPortFree(port);
+    },
+  };
+}
+
+/**
+ * Whether this config is being resolved by something other than a dev server about to bind `server.port`.
+ */
+
+/*
+ * Several independent signals, because any one alone is a single point of failure: Vitest sets `VITEST` before the config loads and its resolved config carries a `test` block that a
+ */
+
+/*
+ * plain dev server never has, and `middlewareMode` marks an embedder such as Storybook or an SSR harness that never listens itself.
+ */
+
+/*
+ * `vite preview` is caught in the `config` hook above, the only place it declares itself.
+ */
+
+/*
+ * A false positive costs a port that is not reclaimed; a false negative kills the developer's session, so every doubtful case resolves to "do not touch it".
+ */
+function isNotBindingTheDevPort(config) {
+  return Boolean(
+    config.server?.middlewareMode ||
+    process.env.VITEST ||
+    process.env.VITEST_WORKER_ID ||
+    config.test,
+  );
+}
+
+/** PIDs of processes LISTENing on the port (IPv4 + IPv6), via lsof. */
+function listenerPids(port) {
+  try {
+    const out = execFileSync("lsof", ["-ti", `tcp:${port}`, "-sTCP:LISTEN"], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    });
+    return [
+      ...new Set(
+        out
+          .split("\n")
+          .map((line) => Number(line.trim()))
+          .filter((pid) => Number.isInteger(pid) && pid > 0),
+      ),
+    ];
+  } catch {
+    // lsof missing, or nothing listening (non-zero exit) -> nothing to reclaim
+    return [];
+  }
+}
+
+/** Resolve once the port stops accepting connections, or the timeout elapses. */
+function waitForPortFree(port, timeoutMs = 2000) {
+  const deadline = Date.now() + timeoutMs;
+  return new Promise((resolve) => {
+    const probe = () => {
+      const socket = net.connect({ port, host: "127.0.0.1" });
+      socket.once("connect", () => {
+        socket.destroy();
+        if (Date.now() > deadline) return resolve();
+        setTimeout(probe, 50);
+      });
+      socket.once("error", () => {
+        socket.destroy();
+        resolve(); // connection refused -> port is free
+      });
+    };
+    probe();
+  });
+}
+
+/** An explicit opt-in to take a port from a server that is still serving. */
+function isForced() {
+  return process.env.RECLAIM_PORT_FORCE === "1";
+}
+
+/**
+ * Whether something on this port still answers a request.
+ */
+
+/*
+ * WHY both stacks: vite binds `localhost`, which on macOS resolves to `::1` first, so a running dev server routinely appears on IPv6 ONLY.
+ */
+
+/*
+ * A probe to 127.0.0.1 is refused, the port reads as free, and the guard waves through the exact start it exists to stop.
+ */
+
+/*
+ * Verified against a live server on 3160: the IPv4-only probe returned "free" while the server was serving.
+ */
+
+/*
+ * WHY a written request and not a bare `connect`: connecting succeeds against a listener that will never reply, and telling those two apart is the whole job.
+ */
+
+/*
+ * Any byte back counts; the status line does not matter.
+ */
+function isServing(port, timeoutMs = 1000) {
+  return Promise.all(HOSTS.map((host) => answers(host, port, timeoutMs))).then((results) =>
+    results.some(Boolean),
+  );
+}
+
+function answers(host, port, timeoutMs) {
+  return new Promise((resolve) => {
+    let settled = false;
+    const done = (answer) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      socket.destroy();
+      resolve(answer);
+    };
+
+    const timer = setTimeout(() => done(false), timeoutMs);
+    const socket = net.connect({ port, host });
+
+    socket.setTimeout(timeoutMs, () => done(false));
+    socket.once("error", () => done(false));
+    socket.once("data", () => done(true));
+    socket.once("close", () => done(false));
+    socket.once("connect", () => {
+      socket.write(`GET / HTTP/1.0\r\nHost: ${formatHost(host)}:${port}\r\n\r\n`);
+    });
+  });
+}
+
+/** An IPv6 literal needs brackets in a Host header. */
+function formatHost(host) {
+  return host.includes(":") ? `[${host}]` : host;
+}

package/package.json

@@ -1,6 +1,203 @@
 {
   "name": "@heyramzi/utils",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.13.0",
+  "description": "Shared TypeScript decisions for every Studio app: cn, result, formatting, crypto, auth defaults, email, Sentry errors, Umami analytics, OG images, testimonials and the AI model table.",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/heyramzi/vibe-kit.git",
+    "directory": "packages/utils"
+  },
+  "files": [
+    "src",
+    "package.json",
+    "dist"
+  ],
+  "type": "module",
+  "imports": {
+    "#src/vite.js": "./src/vite.js",
+    "#src/*.js": "./src/*.ts",
+    "#src/*": "./src/*"
+  },
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "module": "./src/index.ts",
+      "default": "./dist/index.js"
+    },
+    "./cn": {
+      "types": "./src/cn.ts",
+      "module": "./src/cn.ts",
+      "default": "./dist/cn.js"
+    },
+    "./format": {
+      "types": "./src/format.ts",
+      "module": "./src/format.ts",
+      "default": "./dist/format.js"
+    },
+    "./string": {
+      "types": "./src/string.ts",
+      "module": "./src/string.ts",
+      "default": "./dist/string.js"
+    },
+    "./result": {
+      "types": "./src/result.ts",
+      "module": "./src/result.ts",
+      "default": "./dist/result.js"
+    },
+    "./timing": {
+      "types": "./src/timing.ts",
+      "module": "./src/timing.ts",
+      "default": "./dist/timing.js"
+    },
+    "./math": {
+      "types": "./src/math.ts",
+      "module": "./src/math.ts",
+      "default": "./dist/math.js"
+    },
+    "./collection": {
+      "types": "./src/collection.ts",
+      "module": "./src/collection.ts",
+      "default": "./dist/collection.js"
+    },
+    "./vite": {
+      "types": "./src/vite.d.ts",
+      "default": "./src/vite.js"
+    },
+    "./grab": {
+      "types": "./src/grab.d.ts",
+      "default": "./src/grab.js"
+    },
+    "./crypto": {
+      "types": "./src/crypto.ts",
+      "module": "./src/crypto.ts",
+      "default": "./dist/crypto.js"
+    },
+    "./auth": {
+      "types": "./src/auth/index.ts",
+      "module": "./src/auth/index.ts",
+      "default": "./dist/auth/index.js"
+    },
+    "./email": {
+      "types": "./src/auth/email/index.ts",
+      "module": "./src/auth/email/index.ts",
+      "default": "./dist/auth/email/index.js"
+    },
+    "./errors": {
+      "types": "./src/errors/sentry/index.ts",
+      "module": "./src/errors/sentry/index.ts",
+      "default": "./dist/errors/sentry/index.js"
+    },
+    "./errors/sveltekit": {
+      "types": "./src/errors/sentry/sveltekit.ts",
+      "module": "./src/errors/sentry/sveltekit.ts",
+      "default": "./dist/errors/sentry/sveltekit.js"
+    },
+    "./analytics": {
+      "types": "./src/analytics/client.ts",
+      "module": "./src/analytics/client.ts",
+      "default": "./dist/analytics/client.js"
+    },
+    "./analytics/server": {
+      "types": "./src/analytics/server.ts",
+      "module": "./src/analytics/server.ts",
+      "default": "./dist/analytics/server.js"
+    },
+    "./analytics/svelte": {
+      "types": "./src/analytics/svelte.ts",
+      "module": "./src/analytics/svelte.ts",
+      "default": "./dist/analytics/svelte.js"
+    },
+    "./analytics/umami": {
+      "types": "./src/analytics/umami/protocol.ts",
+      "module": "./src/analytics/umami/protocol.ts",
+      "default": "./dist/analytics/umami/protocol.js"
+    },
+    "./analytics/reporting": {
+      "types": "./src/analytics/umami/reporting.ts",
+      "module": "./src/analytics/umami/reporting.ts",
+      "default": "./dist/analytics/umami/reporting.js"
+    },
+    "./og": {
+      "types": "./src/og/index.ts",
+      "module": "./src/og/index.ts",
+      "default": "./dist/og/index.js"
+    },
+    "./testimonials": {
+      "types": "./src/testimonials/types.ts",
+      "module": "./src/testimonials/types.ts",
+      "default": "./dist/testimonials/types.js"
+    },
+    "./testimonials/server": {
+      "types": "./src/testimonials/server.ts",
+      "module": "./src/testimonials/server.ts",
+      "default": "./dist/testimonials/server.js"
+    },
+    "./testimonials/render-content": {
+      "types": "./src/testimonials/render-content.ts",
+      "module": "./src/testimonials/render-content.ts",
+      "default": "./dist/testimonials/render-content.js"
+    },
+    "./ai": {
+      "types": "./src/ai/models.ts",
+      "module": "./src/ai/models.ts",
+      "default": "./dist/ai/models.js"
+    },
+    "./ai/image": {
+      "types": "./src/ai/image.ts",
+      "module": "./src/ai/image.ts",
+      "default": "./dist/ai/image.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "dependencies": {
+    "clsx": "^2.1.1",
+    "tailwind-merge": "^3.7.0"
+  },
+  "devDependencies": {
+    "@keygraph/shannon": "^3.4.0",
+    "vite-plus": "1.3.0",
+    "vitest": "5.0.5"
+  },
+  "peerDependencies": {
+    "ai": ">=7.0.11",
+    "satori": ">=0.63.2",
+    "satori-html": ">=0.3.2",
+    "sharp": ">=0.33.0",
+    "ultrahtml": ">=1.7.0",
+    "vite": ">=5.0.0",
+    "wawoff2": ">=2.0.1"
+  },
+  "peerDependenciesMeta": {
+    "vite": {
+      "optional": true
+    },
+    "ai": {
+      "optional": true
+    },
+    "satori": {
+      "optional": true
+    },
+    "satori-html": {
+      "optional": true
+    },
+    "ultrahtml": {
+      "optional": true
+    },
+    "wawoff2": {
+      "optional": true
+    },
+    "sharp": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "test": "vp test run",
+    "typecheck": "tsc --noEmit",
+    "shannon": "shannon",
+    "build": "node ../../scripts/build-dist.mjs"
+  },
+  "license": "MIT"
+}