@heyramzi/utils 1.12.0 → 1.13.0

package/dist/ai/image.js

@@ -0,0 +1,220 @@
+import { generateText } from "ai";
+import { gatewayId, IMAGE_OUTPUT_TOKEN_PRICE_USD, resolveImageModelConfig } from "./models.js";
+function providerOptions(config, aspectRatio) {
+    if (config.provider !== "google") {
+        throw new Error(`Provider "${config.provider}" has no image request shape in @heyramzi/utils.`);
+    }
+    return {
+        google: {
+            responseModalities: [
+                "IMAGE"
+            ],
+            ...aspectRatio ? {
+                imageConfig: {
+                    aspectRatio
+                }
+            } : {}
+        }
+    };
+}
+function decodeBase64(value) {
+    const binary = atob(value);
+    const bytes = new Uint8Array(binary.length);
+    for(let index = 0; index < binary.length; index++)bytes[index] = binary.charCodeAt(index);
+    return bytes;
+}
+const OPENAI_QUALITY = {
+    small: "low",
+    medium: "medium",
+    large: "high"
+};
+const OPENAI_SIZE_BY_RATIO = {
+    "16:9": "1536x1024",
+    "3:2": "1536x1024",
+    "1:1": "1024x1024",
+    "2:3": "1024x1536",
+    "9:16": "1024x1536"
+};
+function openAiCost(config, outputTokens) {
+    const perToken = IMAGE_OUTPUT_TOKEN_PRICE_USD[config.modelId];
+    if (!perToken || !outputTokens) return config.pricePerImage;
+    return outputTokens * perToken;
+}
+function openAiKey(explicit) {
+    const env = globalThis.process?.env;
+    const apiKey = explicit ?? env?.OPENAI_API_KEY;
+    if (!apiKey) throw new Error("OPENAI_API_KEY is not set, so no OpenAI image can be drawn.");
+    return apiKey;
+}
+async function postOpenAi(path, body, headers, apiKey) {
+    const response = await fetch(`https://api.openai.com/v1/${path}`, {
+        method: "POST",
+        headers: {
+            Authorization: `Bearer ${apiKey}`,
+            ...headers
+        },
+        body
+    });
+    const json = await response.json().catch(()=>({}));
+    return {
+        ok: response.ok,
+        status: response.status,
+        json
+    };
+}
+async function generateOpenAiImage(config, options, tier) {
+    const size = options.size ?? OPENAI_SIZE_BY_RATIO[options.aspectRatio ?? ""] ?? "auto";
+    const quality = OPENAI_QUALITY[tier];
+    const references = options.references ?? [];
+    const apiKey = openAiKey(options.apiKey);
+    async function call(withFidelity) {
+        if (references.length === 0) {
+            return postOpenAi("images/generations", JSON.stringify({
+                model: config.sdkId,
+                prompt: options.prompt,
+                size,
+                quality,
+                n: 1
+            }), {
+                "Content-Type": "application/json"
+            }, apiKey);
+        }
+        const form = new FormData();
+        form.set("model", config.sdkId);
+        form.set("prompt", options.prompt);
+        form.set("size", size);
+        form.set("quality", quality);
+        form.set("n", "1");
+        if (withFidelity) form.set("input_fidelity", "high");
+        for (const [index, reference] of references.entries()){
+            const extension = reference.mediaType.split("/")[1] ?? "png";
+            form.append("image[]", new Blob([
+                reference.bytes
+            ], {
+                type: reference.mediaType
+            }), `reference-${index + 1}.${extension}`);
+        }
+        return postOpenAi("images/edits", form, {}, apiKey);
+    }
+    let result = await call(references.length > 0);
+    const unknownParam = !result.ok && (result.json.error?.message ?? "").includes("input_fidelity");
+    if (unknownParam) result = await call(false);
+    if (!result.ok) {
+        throw new Error(`${config.modelId} refused the request (${result.status}): ${result.json.error?.message ?? "no message"}`);
+    }
+    const base64 = result.json.data?.[0]?.b64_json;
+    if (!base64) throw new Error(`${config.modelId} returned no image data.`);
+    return {
+        bytes: decodeBase64(base64),
+        mediaType: "image/png",
+        config,
+        priceUsd: openAiCost(config, result.json.usage?.output_tokens),
+        attempts: 1
+    };
+}
+const AGNES_SIZE = {
+    small: "1K",
+    medium: "2K",
+    large: "4K"
+};
+const AGNES_BASE_URL = "https://apihub.agnes-ai.com/v1";
+function agnesKey(explicit) {
+    const env = globalThis.process?.env;
+    const key = explicit ?? env?.AGNES_API_KEY;
+    if (!key) {
+        throw new Error("The agnes image lane needs an API key: pass `apiKey`, or set AGNES_API_KEY.");
+    }
+    return key;
+}
+async function generateAgnesImage(config, options, tier) {
+    const references = options.references ?? [];
+    if (references.length > 0) {
+        throw new Error(`${config.modelId} draws from a prompt only: it refuses a reference image with a 403 that blames the model. Draw through a gateway for anything conditioned on a frame.`);
+    }
+    const body = {
+        model: config.sdkId,
+        prompt: options.prompt,
+        size: options.size ?? AGNES_SIZE[tier],
+        ratio: options.aspectRatio ?? "1:1"
+    };
+    const response = await fetch(`${AGNES_BASE_URL}/images/generations`, {
+        method: "POST",
+        headers: {
+            Authorization: `Bearer ${agnesKey(options.apiKey)}`,
+            "Content-Type": "application/json"
+        },
+        body: JSON.stringify(body)
+    });
+    const json = await response.json().catch(()=>({}));
+    if (!response.ok) {
+        throw new Error(`${config.modelId} refused the request (${response.status}): ${json.error?.message ?? json.message ?? "no message"}`);
+    }
+    const first = json.data?.[0];
+    if (first?.b64_json) {
+        return {
+            bytes: decodeBase64(first.b64_json),
+            mediaType: "image/png",
+            config,
+            priceUsd: config.pricePerImage,
+            attempts: 1
+        };
+    }
+    if (first?.url) {
+        const image = await fetch(first.url);
+        if (!image.ok) {
+            throw new Error(`${config.modelId} returned a url that did not fetch (${image.status}).`);
+        }
+        return {
+            bytes: new Uint8Array(await image.arrayBuffer()),
+            mediaType: image.headers.get("content-type") ?? "image/png",
+            config,
+            priceUsd: config.pricePerImage,
+            attempts: 1
+        };
+    }
+    throw new Error(`${config.modelId} returned no image data.`);
+}
+export async function generateImage(options) {
+    const tier = options.tier ?? "medium";
+    const config = resolveImageModelConfig(tier, options.provider);
+    if (config.provider === "openai") return generateOpenAiImage(config, options, tier);
+    if (config.provider === "agnes") return generateAgnesImage(config, options, tier);
+    const id = gatewayId(config);
+    const model = options.gateway ? options.gateway(id) : id;
+    const attempts = options.attempts ?? 3;
+    let lastText = "";
+    for(let attempt = 1; attempt <= attempts; attempt++){
+        const result = await generateText({
+            model,
+            messages: [
+                {
+                    role: "user",
+                    content: [
+                        {
+                            type: "text",
+                            text: options.prompt
+                        },
+                        ...(options.references ?? []).map((reference)=>({
+                                type: "file",
+                                data: reference.bytes,
+                                mediaType: reference.mediaType
+                            }))
+                    ]
+                }
+            ],
+            providerOptions: providerOptions(config, options.aspectRatio)
+        });
+        const file = result.files.find((entry)=>entry.mediaType.startsWith("image/"));
+        if (file) {
+            return {
+                bytes: file.uint8Array,
+                mediaType: file.mediaType,
+                config,
+                priceUsd: config.pricePerImage,
+                attempts: attempt
+            };
+        }
+        lastText = (result.text ?? "").slice(0, 160);
+    }
+    throw new Error(`${config.modelId} returned no image after ${attempts} attempts${lastText ? `: ${lastText}` : ""}`);
+}

package/dist/ai/models.js

@@ -0,0 +1,261 @@
+export const MODEL_IDS = {
+    xai: {
+        large: "grok-4.7",
+        medium: "grok-4.7",
+        small: "grok-4.7"
+    },
+    google: {
+        large: "gemini-3.8-flash",
+        medium: "gemini-3.8-flash",
+        small: "gemini-3.5-flash-lite"
+    },
+    anthropic: {
+        large: "claude-opus-5-5",
+        medium: "claude-sonnet-5-5",
+        small: "claude-haiku-5-5"
+    },
+    groq: {
+        large: "openai/gpt-oss-120b",
+        medium: "openai/gpt-oss-120b",
+        small: "openai/gpt-oss-20b"
+    }
+};
+export const MODEL_CATALOG = {
+    "grok-4.7": {
+        modelId: "grok-4.7",
+        sdkId: "grok-4.7",
+        provider: "xai",
+        tier: "large",
+        pricing: {
+            input: 2.0,
+            output: 6.0
+        },
+        gatewayId: "spacexai/grok-4.7"
+    },
+    "gemini-3.8-flash": {
+        modelId: "gemini-3.8-flash",
+        sdkId: "gemini-3.8-flash",
+        provider: "google",
+        tier: "medium",
+        pricing: {
+            input: 1.5,
+            output: 7.5
+        }
+    },
+    "gemini-3.5-flash-lite": {
+        modelId: "gemini-3.5-flash-lite",
+        sdkId: "gemini-3.5-flash-lite",
+        provider: "google",
+        tier: "small",
+        pricing: {
+            input: 0.3,
+            output: 2.5
+        }
+    },
+    "claude-opus-5-5": {
+        modelId: "claude-opus-5-5",
+        sdkId: "claude-opus-5-5",
+        gatewayId: "anthropic/claude-opus-5.5",
+        provider: "anthropic",
+        tier: "large",
+        pricing: {
+            input: 4.0,
+            output: 20.0
+        }
+    },
+    "claude-sonnet-5-5": {
+        modelId: "claude-sonnet-5-5",
+        sdkId: "claude-sonnet-5-5",
+        gatewayId: "anthropic/claude-sonnet-5.5",
+        provider: "anthropic",
+        tier: "medium",
+        pricing: {
+            input: 2.0,
+            output: 10.0
+        }
+    },
+    "claude-haiku-5-5": {
+        modelId: "claude-haiku-5-5",
+        sdkId: "claude-haiku-5-5",
+        gatewayId: "anthropic/claude-haiku-5.5",
+        provider: "anthropic",
+        tier: "small",
+        pricing: {
+            input: 0.1,
+            output: 0.5
+        }
+    },
+    "claude-fable-5-1": {
+        modelId: "claude-fable-5-1",
+        sdkId: "claude-fable-5-1",
+        gatewayId: "anthropic/claude-fable-5.1",
+        provider: "anthropic",
+        tier: "large",
+        pricing: {
+            input: 10.0,
+            output: 50.0
+        }
+    },
+    "gemini-3.6-flash": {
+        modelId: "gemini-3.6-flash",
+        sdkId: "gemini-3.6-flash",
+        provider: "google",
+        tier: "medium",
+        pricing: {
+            input: 1.5,
+            output: 7.5
+        }
+    },
+    "gpt-5.6-luna": {
+        modelId: "gpt-5.6-luna",
+        sdkId: "gpt-5.6-luna",
+        provider: "openai",
+        tier: "small",
+        pricing: {
+            input: 0.2,
+            output: 1.2
+        }
+    },
+    "gpt-6-luna": {
+        modelId: "gpt-6-luna",
+        sdkId: "gpt-6-luna",
+        provider: "openai",
+        tier: "small",
+        pricing: {
+            input: 0.1,
+            output: 0.5
+        }
+    },
+    "gpt-6.1-sol": {
+        modelId: "gpt-6.1-sol",
+        sdkId: "gpt-6.1-sol",
+        provider: "openai",
+        tier: "large",
+        pricing: {
+            input: 2.0,
+            output: 10.0
+        }
+    },
+    "openai/gpt-oss-120b": {
+        modelId: "openai/gpt-oss-120b",
+        sdkId: "openai/gpt-oss-120b",
+        gatewayId: "openai/gpt-oss-120b",
+        provider: "groq",
+        tier: "large",
+        pricing: {
+            input: 0.15,
+            output: 0.6
+        }
+    },
+    "openai/gpt-oss-20b": {
+        modelId: "openai/gpt-oss-20b",
+        sdkId: "openai/gpt-oss-20b",
+        gatewayId: "openai/gpt-oss-20b",
+        provider: "groq",
+        tier: "small",
+        pricing: {
+            input: 0.075,
+            output: 0.3
+        }
+    }
+};
+export const DEFAULT_PROVIDER = "xai";
+export const EMBEDDING_MODEL = {
+    modelId: "gemini-embedding-2-preview",
+    gatewayId: "google/gemini-embedding-2",
+    provider: "google",
+    dimensions: 768
+};
+export const EMBEDDING_DIMENSIONS = EMBEDDING_MODEL.dimensions;
+export function gatewayId(config) {
+    return config.gatewayId ?? `${config.provider}/${config.sdkId}`;
+}
+export function getModelConfig(id) {
+    const config = MODEL_CATALOG[id];
+    if (!config) {
+        throw new Error(`Missing model config for model "${id}".`);
+    }
+    return config;
+}
+export function resolveModelConfig(tier, provider = DEFAULT_PROVIDER) {
+    const ids = MODEL_IDS;
+    const modelId = ids[provider]?.[tier];
+    if (!modelId) {
+        throw new Error(`Missing model ID for provider "${provider}" and tier "${tier}".`);
+    }
+    return getModelConfig(modelId);
+}
+export function model(tier, provider = DEFAULT_PROVIDER) {
+    return gatewayId(resolveModelConfig(tier, provider));
+}
+export const IMAGE_MODEL_IDS = {
+    google: {
+        small: "gemini-3.1-flash-lite-image",
+        medium: "gemini-3.1-flash-lite-image",
+        large: "gemini-nano-banana-2.1"
+    },
+    openai: {
+        small: "gpt-image-2",
+        medium: "gpt-image-2",
+        large: "gpt-image-2"
+    },
+    agnes: {
+        small: "agnes-image-2.5-flash",
+        medium: "agnes-image-2.5-flash",
+        large: "agnes-image-2.5-flash"
+    }
+};
+export const IMAGE_MODEL_CATALOG = {
+    "gemini-3.1-flash-lite-image": {
+        modelId: "gemini-3.1-flash-lite-image",
+        sdkId: "gemini-3.1-flash-lite-image",
+        provider: "google",
+        tier: "small",
+        pricePerImage: 0.034
+    },
+    "gemini-nano-banana-2.1": {
+        modelId: "gemini-nano-banana-2.1",
+        sdkId: "gemini-nano-banana-2.1",
+        provider: "google",
+        tier: "large",
+        pricePerImage: 0.067
+    },
+    "gemini-3-pro-image": {
+        modelId: "gemini-3-pro-image",
+        sdkId: "gemini-3-pro-image",
+        provider: "google",
+        tier: "large",
+        pricePerImage: 0.134
+    },
+    "gpt-image-2": {
+        modelId: "gpt-image-2",
+        sdkId: "gpt-image-2",
+        provider: "openai",
+        tier: "medium",
+        pricePerImage: 0.032
+    },
+    "agnes-image-2.5-flash": {
+        modelId: "agnes-image-2.5-flash",
+        sdkId: "agnes-image-2.5-flash",
+        provider: "agnes",
+        tier: "medium",
+        pricePerImage: 0
+    }
+};
+export const IMAGE_OUTPUT_TOKEN_PRICE_USD = {
+    "gpt-image-2": 30 / 1_000_000
+};
+export const DEFAULT_IMAGE_PROVIDER = "google";
+export function resolveImageModelConfig(tier, provider = DEFAULT_IMAGE_PROVIDER) {
+    const modelId = IMAGE_MODEL_IDS[provider]?.[tier];
+    const config = modelId ? IMAGE_MODEL_CATALOG[modelId] : undefined;
+    if (!config) {
+        throw new Error(`Missing image model for provider "${provider}" and tier "${tier}".`);
+    }
+    return config;
+}
+export function imagePriceUsd(modelId) {
+    const direct = IMAGE_MODEL_CATALOG[modelId];
+    if (direct) return direct.pricePerImage;
+    return Object.values(IMAGE_MODEL_CATALOG).find((config)=>config.sdkId === modelId)?.pricePerImage ?? null;
+}

package/dist/analytics/client.js

@@ -0,0 +1,57 @@
+import "./types.js";
+let active = false;
+export function initAnalytics(config) {
+    stop();
+    if (config.disabled || typeof window === "undefined") return stop;
+    active = true;
+    injectScript(config);
+    return stop;
+}
+function stop() {
+    active = false;
+}
+export function track(event, meta) {
+    if (!active || typeof window === "undefined" || !window.umami) return;
+    try {
+        if (meta) {
+            window.umami.track(event, meta);
+        } else {
+            window.umami.track(event);
+        }
+    } catch  {}
+}
+export function trackRevenue(args) {
+    const meta = {
+        revenue: args.value,
+        currency: args.currency
+    };
+    if (args.plan) meta.plan = args.plan;
+    if (args.transactionId) meta.transaction_id = args.transactionId;
+    track(args.event, meta);
+}
+export function setProfileId(id) {
+    if (!active || typeof window === "undefined" || !window.umami?.identify) return;
+    try {
+        window.umami.identify(id ? {
+            profileId: id
+        } : {});
+    } catch  {}
+}
+function injectScript(umami) {
+    if (typeof document === "undefined") return;
+    if (!(umami.autoInjectScript ?? true)) return;
+    if (document.querySelector(`script[data-website-id="${umami.websiteId}"]`)) return;
+    const script = document.createElement("script");
+    script.defer = true;
+    script.src = `${umami.host.replace(/\/+$/, "")}/script.js`;
+    script.dataset.websiteId = umami.websiteId;
+    if (umami.performance) script.dataset.performance = "true";
+    if (umami.tag) script.dataset.tag = umami.tag;
+    if (umami.beforeSend) script.dataset.beforeSend = umami.beforeSend;
+    if (umami.domains?.length) script.dataset.domains = umami.domains.join(",");
+    if (umami.doNotTrack) script.dataset.doNotTrack = "true";
+    if (umami.autoTrack === false) script.dataset.autoTrack = "false";
+    if (umami.excludeSearch) script.dataset.excludeSearch = "true";
+    if (umami.excludeHash) script.dataset.excludeHash = "true";
+    document.head.appendChild(script);
+}

package/dist/analytics/server.js

@@ -0,0 +1,54 @@
+import { buildSendBody, UMAMI_ENDPOINTS } from "./umami/protocol.js";
+const DEFAULT_USER_AGENT = "Mozilla/5.0 Marketing/1.0";
+const TIMEOUT_MS = 3000;
+let _config = null;
+export function initServer(config) {
+    _config = config;
+}
+export async function trackServer(name, data, options) {
+    const { url, id } = typeof options === "string" ? {
+        url: options,
+        id: undefined
+    } : options ?? {};
+    try {
+        if (!_config) throw new Error("Call initServer() before tracking events");
+        const body = buildSendBody({
+            websiteId: _config.websiteId,
+            hostname: _config.hostname,
+            name,
+            url,
+            data
+        });
+        const payload = id ? {
+            ...body.payload,
+            id
+        } : body.payload;
+        const response = await fetch(`${_config.hostUrl.replace(/\/$/, "")}${UMAMI_ENDPOINTS.send}`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                "User-Agent": _config.userAgent ?? DEFAULT_USER_AGENT
+            },
+            body: JSON.stringify({
+                ...body,
+                payload
+            }),
+            signal: AbortSignal.timeout(TIMEOUT_MS)
+        });
+        const text = await response.text();
+        if (!response.ok || text.includes("beep")) {
+            throw new Error(`HTTP ${response.status}: ${text.slice(0, 120)}`);
+        }
+        return true;
+    } catch (err) {
+        console.error(`[analytics] Server track failed for ${name}:`, err);
+        return false;
+    }
+}
+export function trackServerRevenue(name, revenue, currency, data, options) {
+    return trackServer(name, {
+        ...data,
+        revenue,
+        currency
+    }, options);
+}

package/dist/analytics/svelte.js

@@ -0,0 +1,24 @@
+const DEFAULT_HOST = "https://your-umami-instance.com";
+export function umamiScriptAttrs(websiteId, options) {
+    const host = options?.hostUrl ?? DEFAULT_HOST;
+    const attrs = {
+        src: `${host}/script.js`,
+        "data-website-id": websiteId
+    };
+    if (options?.domains?.length) {
+        attrs["data-domains"] = options.domains.join(",");
+    }
+    if (options?.beforeSend) {
+        attrs["data-before-send"] = options.beforeSend;
+    }
+    if (options?.doNotTrack) {
+        attrs["data-do-not-track"] = "true";
+    }
+    if (options?.performance) {
+        attrs["data-performance"] = "true";
+    }
+    if (options?.tag) {
+        attrs["data-tag"] = options.tag;
+    }
+    return attrs;
+}

package/dist/analytics/umami/protocol.js

@@ -0,0 +1,35 @@
+export const UMAMI_ENDPOINTS = {
+    send: "/api/send"
+};
+export function coerceData(data) {
+    if (!data) return undefined;
+    const out = {};
+    for (const [key, value] of Object.entries(data)){
+        if (value === undefined || value === null) continue;
+        if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+            out[key] = value;
+        } else {
+            out[key] = String(value);
+        }
+    }
+    return Object.keys(out).length > 0 ? out : undefined;
+}
+export function buildSendBody(input) {
+    const data = coerceData(input.data);
+    const payload = {
+        website: input.websiteId,
+        url: input.url ?? "/"
+    };
+    if (input.name) payload.name = input.name;
+    if (input.hostname) payload.hostname = input.hostname;
+    if (input.title) payload.title = input.title;
+    if (input.referrer) payload.referrer = input.referrer;
+    if (input.language) payload.language = input.language;
+    if (input.screen) payload.screen = input.screen;
+    if (data) payload.data = data;
+    if (input.userAgent) payload.userAgent = input.userAgent;
+    return {
+        type: "event",
+        payload
+    };
+}