@heyramzi/utils 0.0.0-stage → 1.12.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ramzi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,113 @@
-# Temporary Holding Version
+> [!IMPORTANT]
+> This submodule is originally created and maintained in `Studio/vibe-kit/modules`. Changes should be made and pushed from there. We are the creators and maintainers of this submodule.
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @heyramzi/utils
+
+Shared utility functions used across all workspace projects.
+
+## Install
+
+```bash
+pnpm add @heyramzi/utils
+```
+
+In the workspace, use `"@heyramzi/utils": "workspace:*"` in your `package.json`.
+
+## Exports
+
+### Main entry (`.`)
+
+All utilities re-exported from a single barrel:
+
+```ts
+import { cn, formatDate, debounce, groupBy } from "@heyramzi/utils";
+```
+
+### Subpath exports
+
+Some modules are also a direct import for tree-shaking. The rest come from the barrel only.
+
+| Subpath | Exports |
+| --- | --- |
+| `@heyramzi/utils/cn` | `cn`, `WithElementRef`, `WithoutChild`, `WithoutChildren`, `WithoutChildrenOrChild` |
+| `@heyramzi/utils/format` | `formatDate`, `formatCurrency`, `formatAmount`, `formatMillisecondsToHours`, `formatRelativeTime` |
+| `@heyramzi/utils/string` | `slugify`, `generateSlug`, `buildSearchParams`, `parseJSON`, `parseCommaSeparatedList`, `matchesQuery` |
+| `@heyramzi/utils/timing` | `debounce`, `throttle`, `sleep` |
+| `@heyramzi/utils/math` | `clamp` |
+| `@heyramzi/utils/collection` | `groupBy` |
+| `@heyramzi/utils/result` | `Ok`, `Err`, `tryCatch`, `tryCatchAsync`, `Result` |
+| `@heyramzi/utils/crypto` | `encryptSecret`, `decryptSecret`, `encryptSecretWithKey`, `decryptSecretWithKey`, `packSecret`, `unpackSecret`, `SecretCiphertext` |
+| `@heyramzi/utils/vite` | `packageImportsOverKitAlias`, `reclaimPort` |
+| `@heyramzi/utils/grab` | Side effect only: `if (dev) import("@heyramzi/utils/grab")`, then Alt+Click copies an element's HTML and Svelte component stack |
+
+Barrel only: `fetchApi`, `isCacheExpired`, `setLogger`, `log`.
+
+## Usage in projects
+
+Projects re-export what they need from their own `src/lib/utils.ts`:
+
+```ts
+// src/lib/utils.ts
+export { cn, formatDate, formatRelativeTime, debounce } from "@heyramzi/utils";
+export type { WithoutChild, WithoutChildren, WithElementRef } from "@heyramzi/utils";
+```
+
+This keeps the public API stable per-project while sourcing from a single implementation.
+
+## Logger
+
+`log()` does nothing until an app calls `setLogger()` once at startup with an implementation of the `Logger` interface. It never throws.
+
+## Secret Encryption
+
+`@heyramzi/utils/crypto` exists for reversible encryption of OAuth tokens and API keys at rest in app backends. It does not store anything for you and it does not implement provider-specific auth flows.
+
+Import it as a server-only subpath:
+
+```ts
+import { decryptSecret, encryptSecret } from "@heyramzi/utils/crypto";
+```
+
+It uses AES-256-GCM with:
+
+- a 32-byte master key from `HEYRAMZI_UTILS_CRYPTO_KEY`
+- a fresh random 12-byte IV for every encryption
+- base64 output for both `ciphertext` and `iv`
+
+`ciphertext` includes the GCM auth tag, so consumers only need to persist `ciphertext` and `iv`. Use this helper only when the secret must be recovered later. It is not for password storage or hashing.
+
+If an app already has its own env var name or stores encrypted secrets in a single database field, use the additive helpers:
+
+- `encryptSecretWithKey` / `decryptSecretWithKey` to pass a raw 32-byte key directly
+- `packSecret` / `unpackSecret` to bridge `{ ciphertext, iv }` with a single base64 payload
+
+## Dependencies
+
+- `clsx` + `tailwind-merge` (for `cn`)
+- `vite` (optional peer, only for `@heyramzi/utils/vite`)
+
+## Tooling scripts
+
+This package hosts two code-intelligence CLIs as devDependencies, invoked from the utils package so they have a stable home. They are not part of the runtime library surface.
+
+| Script         | Command                     | What it does                                                                                                                                                                    |
+| -------------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `pnpm fallow`  | [`fallow`][fallow]          | Static analysis for TypeScript/JavaScript: unused files/exports/deps, circular references, copy-pasted blocks, complexity hotspots, architecture boundary drift.                |
+| `pnpm shannon` | [`@keygraph/shannon`][shan] | Autonomous AI pentester for web apps and APIs. Reads a source checkout, runs exploits against a live URL, reports only verified vulnerabilities. Requires Docker and Node 18+. |
+
+Run from `packages/utils`:
+
+```bash
+pnpm fallow                 # summary across the codebase
+pnpm fallow dead-code       # just unused code
+pnpm fallow audit --format json
+pnpm shannon setup
+pnpm shannon start -u https://example.com -r /path/to/repo
+```
+
+[fallow]: https://github.com/fallow-rs/fallow
+[shan]: https://github.com/KeygraphHQ/shannon
+
+## Removed
+
+The `error-reporter`, `image` and `sveltekit` modules are gone, along with `getErrorMessage`, `CACHE_TTL`, `getCacheExpiry`, `getLogger` and `formatTime`. Nothing imported them, and the `sharp` and SvelteKit peers went with them.

package/package.json

@@ -1,6 +1,105 @@
 {
   "name": "@heyramzi/utils",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.12.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"
+  ],
+  "type": "module",
+  "imports": {
+    "#src/vite.js": "./src/vite.js",
+    "#src/*.js": "./src/*.ts",
+    "#src/*": "./src/*"
+  },
+  "exports": {
+    ".": "./src/index.ts",
+    "./cn": "./src/cn.ts",
+    "./format": "./src/format.ts",
+    "./string": "./src/string.ts",
+    "./result": "./src/result.ts",
+    "./timing": "./src/timing.ts",
+    "./math": "./src/math.ts",
+    "./collection": "./src/collection.ts",
+    "./vite": {
+      "types": "./src/vite.d.ts",
+      "default": "./src/vite.js"
+    },
+    "./grab": {
+      "types": "./src/grab.d.ts",
+      "default": "./src/grab.js"
+    },
+    "./crypto": "./src/crypto.ts",
+    "./auth": "./src/auth/index.ts",
+    "./email": "./src/auth/email/index.ts",
+    "./errors": "./src/errors/sentry/index.ts",
+    "./errors/sveltekit": "./src/errors/sentry/sveltekit.ts",
+    "./analytics": "./src/analytics/client.ts",
+    "./analytics/server": "./src/analytics/server.ts",
+    "./analytics/svelte": "./src/analytics/svelte.ts",
+    "./analytics/umami": "./src/analytics/umami/protocol.ts",
+    "./analytics/reporting": "./src/analytics/umami/reporting.ts",
+    "./og": "./src/og/index.ts",
+    "./testimonials": "./src/testimonials/types.ts",
+    "./testimonials/server": "./src/testimonials/server.ts",
+    "./testimonials/render-content": "./src/testimonials/render-content.ts",
+    "./ai": "./src/ai/models.ts",
+    "./ai/image": "./src/ai/image.ts"
+  },
+  "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"
+  },
+  "license": "MIT"
+}

package/src/ai/image-agnes.test.ts

@@ -0,0 +1,130 @@
+import { afterEach, describe, expect, it, vi } from "vite-plus/test";
+import { generateImage } from "#src/ai/image.js";
+
+function mockFetch(replies: { ok?: boolean; status?: number; json?: unknown; bytes?: string }[]) {
+  const calls: { url: string; init?: RequestInit }[] = [];
+  let index = 0;
+  vi.stubGlobal(
+    "fetch",
+    vi.fn(async (url: string | URL, init?: RequestInit) => {
+      calls.push({ url: String(url), init });
+      const reply = replies[Math.min(index++, replies.length - 1)];
+      return {
+        ok: reply.ok ?? true,
+        status: reply.status ?? 200,
+        headers: new Headers({ "content-type": "image/webp" }),
+        json: async () => reply.json ?? {},
+        arrayBuffer: async () => new TextEncoder().encode(reply.bytes ?? "").buffer,
+      } as unknown as Response;
+    }),
+  );
+  return calls;
+}
+
+const OPTS = { prompt: "a poster", apiKey: "agnes_test" };
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+  vi.unstubAllEnvs();
+});
+
+describe("generateImage on the agnes lane", () => {
+  it("posts to the Agnes images endpoint and returns decoded bytes at no cost", async () => {
+    const calls = mockFetch([{ json: { data: [{ b64_json: btoa("PNGDATA") }] } }]);
+
+    const image = await generateImage({ ...OPTS, provider: "agnes" });
+
+    expect(calls[0].url).toBe("https://apihub.agnes-ai.com/v1/images/generations");
+    expect(new TextDecoder().decode(image.bytes)).toBe("PNGDATA");
+    expect(image.priceUsd).toBe(0);
+    expect(image.config.provider).toBe("agnes");
+  });
+
+  // The tier is the output resolution, because that is how Agnes prices a frame.
+  it.each([
+    ["small", "1K"],
+    ["medium", "2K"],
+    ["large", "4K"],
+  ] as const)("maps the %s tier to size %s", async (tier, size) => {
+    const calls = mockFetch([{ json: { data: [{ b64_json: btoa("x") }] } }]);
+
+    await generateImage({ ...OPTS, provider: "agnes", tier });
+
+    expect(JSON.parse(String(calls[0].init?.body))).toMatchObject({ size, ratio: "1:1" });
+  });
+
+  // The regression guard for a 5-minute hang. Asking Agnes for base64 makes it hold the connection without sending headers, and undici kills the request at exactly 300s with UND_ERR_HEADERS_TIMEOUT.
+
+  // The same prompt answers in 35s in url mode. Measured 31 Aug 2026.
+  it("never asks for base64, which is what made the request time out", async () => {
+    const calls = mockFetch([
+      { json: { data: [{ url: "https://cdn.agnes/f.png" }] } },
+      { bytes: "PNG" },
+    ]);
+
+    await generateImage({ ...OPTS, provider: "agnes" });
+
+    const body = JSON.parse(String(calls[0].init?.body));
+    expect(body.return_base64).toBeUndefined();
+    expect(body.extra_body).toBeUndefined();
+  });
+
+  // Measured 9 Sep 2026: the lane carries text-to-image only, and reports a reference as `403 team not allowed to access model`, which reads as a dead lane rather than a
+
+  // missing capability. It used to send the reference as a data URI and let the API answer that; refusing before the call is what makes the error true,
+
+  // and no request is worth spending to be told this.
+  it("refuses a reference before spending a call, and says why", async () => {
+    const calls = mockFetch([{ json: { data: [{ b64_json: btoa("x") }] } }]);
+
+    await expect(
+      generateImage({
+        ...OPTS,
+        provider: "agnes",
+        references: [{ bytes: new TextEncoder().encode("REF"), mediaType: "image/jpeg" }],
+      }),
+    ).rejects.toThrow("draws from a prompt only");
+
+    expect(calls).toHaveLength(0);
+  });
+
+  it("carries the aspect ratio through as `ratio`", async () => {
+    const calls = mockFetch([{ json: { data: [{ b64_json: btoa("x") }] } }]);
+
+    await generateImage({ ...OPTS, provider: "agnes", aspectRatio: "16:9" });
+
+    expect(JSON.parse(String(calls[0].init?.body)).ratio).toBe("16:9");
+  });
+
+  // An account that ignores `return_base64` answers with a url instead. Fetching
+  // it here keeps every caller on one return shape: bytes.
+  it("fetches the url when the account answers with one instead of base64", async () => {
+    const calls = mockFetch([
+      { json: { data: [{ url: "https://cdn.agnes/frame.webp" }] } },
+      { bytes: "WEBPDATA" },
+    ]);
+
+    const image = await generateImage({ ...OPTS, provider: "agnes" });
+
+    expect(calls[1].url).toBe("https://cdn.agnes/frame.webp");
+    expect(new TextDecoder().decode(image.bytes)).toBe("WEBPDATA");
+    expect(image.mediaType).toBe("image/webp");
+  });
+
+  it("carries the provider's own message when it refuses", async () => {
+    mockFetch([{ ok: false, status: 400, json: { error: { message: "ratio not supported" } } }]);
+
+    await expect(generateImage({ ...OPTS, provider: "agnes" })).rejects.toThrow(
+      "ratio not supported",
+    );
+  });
+
+  it("names the env var when no key is anywhere", async () => {
+    vi.stubEnv("AGNES_API_KEY", "");
+    mockFetch([{ json: {} }]);
+
+    await expect(generateImage({ prompt: "p", provider: "agnes" })).rejects.toThrow(
+      "AGNES_API_KEY",
+    );
+  });
+});