@heyramzi/utils 0.0.0-stage → 1.12.0

package/src/ai/models.ts

@@ -0,0 +1,450 @@
+export type Provider = string;
+export type ModelTier = "small" | "medium" | "large";
+export type ModelId = string;
+
+export type ModelPricing = { input: number; output: number };
+
+export type ModelConfig = {
+  modelId: ModelId;
+  sdkId: string;
+  provider: Provider;
+  tier: ModelTier;
+  pricing: ModelPricing;
+  /**
+   * What this model is called on a multi-provider gateway that addresses every vendor through one endpoint (Vercel AI Gateway), which is `<vendor slug>/<model>`.
+   */
+
+  /*
+   * WHY it cannot be derived from `sdkId` in every case, measured against the live Vercel catalog on 31 Aug 2026: Anthropic's own ids separate the version with dashes (`claude-haiku-5-5`) where
+   */
+
+  /*
+   * the gateway uses a dot (`anthropic/claude-haiku-5.5`), and a model whose `sdkId` already carries a slash (`openai/gpt-oss-120b`, served by groq) would resolve to a doubled path.
+   */
+
+  /*
+   * Left absent the resolver builds `<slug>/<sdkId>`, which is right for google and openai.
+   */
+  gatewayId?: string;
+};
+
+export type ModelMatrix = Partial<Record<Provider, Partial<Record<ModelTier, ModelId>>>>;
+
+export type EmbeddingConfig = {
+  modelId: string;
+  provider: Provider;
+  dimensions: number;
+  /** See `ModelConfig.gatewayId`. */
+  gatewayId?: string;
+};
+
+export const MODEL_IDS = {
+  xai: { large: "grok-4.7", medium: "grok-4.7", small: "grok-4.7" },
+  // 3.1 Pro answered 404 on the gateway and scored below 3.8 Flash on Artificial Analysis, 8 Oct 2026.
+  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" },
+  // WHY 120b sits on two tiers: Groq publishes a price for gpt-oss-120b and
+
+  // gpt-oss-20b and the models between them move often, so the matrix uses the two that are priced rather than a third whose cost would have to be guessed.
+  groq: {
+    large: "openai/gpt-oss-120b",
+    medium: "openai/gpt-oss-120b",
+    small: "openai/gpt-oss-20b",
+  },
+} as const satisfies Record<Provider, Record<ModelTier, ModelId>>;
+
+export const MODEL_CATALOG: Record<ModelId, ModelConfig> = {
+  "grok-4.7": {
+    modelId: "grok-4.7",
+    sdkId: "grok-4.7",
+    provider: "xai",
+    tier: "large",
+    pricing: { input: 2.0, output: 6.0 },
+    // The gateway lists Grok under `spacexai/`. `xai/` still answers, but only as an unlisted alias.
+    gatewayId: "spacexai/grok-4.7",
+  },
+  // WHY the pricing is not the number Google is currently charging: 3.8 Flash
+
+  // launched at an introductory $0.75/$3.75 that expires 2026-12-31 and reverts to the pair below, which is also what 3.6 Flash cost.
+
+  // Recording the rate that outlives the discount keeps a cost estimate from halving overnight in January.
+  "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 },
+  },
+  // Prompts past 100K input tokens bill at $0.50 / $2.50.
+  "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 },
+  },
+  // List rate $10 / $50 per 1M tokens, the one upsys's ai-spend script bills against.
+  "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 },
+  },
+  // 3.6 Flash cost the same $1.50 / $7.50 that 3.8 Flash reverts to.
+  "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 },
+  },
+  // Short-context rate from OpenAI's pricing page, 31 Aug 2026.
+  "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 },
+  },
+  // Kilo's live catalogue, read 8 Oct 2026.
+  "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 },
+  },
+  // Prices read from Groq's published rates on 23 Aug 2026.
+
+  // The batch API and cached input are both cheaper; the synchronous rate is recorded because that is what every call in this package makes.
+  "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 },
+  },
+};
+
+/** The provider `model(tier)` answers with when the caller names none. */
+export const DEFAULT_PROVIDER: Provider = "xai";
+
+export const EMBEDDING_MODEL: EmbeddingConfig = {
+  modelId: "gemini-embedding-2-preview",
+  gatewayId: "google/gemini-embedding-2",
+  provider: "google",
+  dimensions: 768,
+};
+
+export const EMBEDDING_DIMENSIONS = EMBEDDING_MODEL.dimensions;
+
+/** The id the AI gateway knows a model by: `generateText({ model: gatewayId(config) })`. */
+export function gatewayId(config: {
+  provider: Provider;
+  sdkId: string;
+  gatewayId?: string;
+}): string {
+  return config.gatewayId ?? `${config.provider}/${config.sdkId}`;
+}
+
+export function getModelConfig(id: ModelId): ModelConfig {
+  const config = MODEL_CATALOG[id];
+  if (!config) {
+    throw new Error(`Missing model config for model "${id}".`);
+  }
+  return config;
+}
+
+/** What a tier resolves to, for a price or a badge. */
+export function resolveModelConfig(
+  tier: ModelTier,
+  provider: Provider = DEFAULT_PROVIDER,
+): ModelConfig {
+  const ids: ModelMatrix = MODEL_IDS;
+  const modelId = ids[provider]?.[tier];
+  if (!modelId) {
+    throw new Error(`Missing model ID for provider "${provider}" and tier "${tier}".`);
+  }
+  return getModelConfig(modelId);
+}
+
+/** The gateway id for a tier: `generateText({ model: model("medium") })`. */
+export function model(tier: ModelTier, provider: Provider = DEFAULT_PROVIDER): string {
+  return gatewayId(resolveModelConfig(tier, provider));
+}
+
+// --------------------------------------------------------------------- images
+
+/**
+ * Image generation, on the same three tiers as text.
+ */
+
+/*
+ * WHY the tiers exist: every caller used to name a model id by hand (`gemini-3.1-flash-image-preview` in three upsys files, `gemini-3-pro-image` in a fourth),
+ */
+
+/*
+ * so the choice between a $0.034 frame and a $0.134 one was scattered across four repos and nothing recorded what a frame cost.
+ */
+
+/*
+ * A tier says what the frame is FOR (a sample, a shipped asset, a hero) and the catalog says which model and what it costs.
+ */
+
+/*
+ * An image model here is a language model that answers with image parts, not an `experimental_generateImage` model: that is what the Gemini image family is,
+ */
+
+/*
+ * and it is why references, multi-turn edits and text-in-image all work.
+ */
+export type ImageModelConfig = {
+  modelId: ModelId;
+  sdkId: string;
+  provider: Provider;
+  tier: ModelTier;
+  /**
+   * USD for one returned image at 1K, which is the 1,120 image-token bracket every caller asks for.
+   */
+
+  /*
+   * Google bills an image as a fixed token count on the output side, so a frame's cost is a property of the model and its resolution, never of the request.
+   */
+  pricePerImage: number;
+  /** See `ModelConfig.gatewayId`. */
+  gatewayId?: string;
+};
+
+export type ImageModelMatrix = Partial<Record<Provider, Partial<Record<ModelTier, ModelId>>>>;
+
+/**
+ * Verified 26 Aug 2026 by calling each id through the Cloudflare AI Gateway and reading an image back, and priced off ai.google.dev/gemini-api/docs/pricing on the same day:
+ */
+
+/* $30, $60 and $120 per 1M image tokens. */
+
+/* 8 Oct 2026: Nano Banana 2 Lite on small and medium, 2.1 on large. Pro has no tier. */
+export const IMAGE_MODEL_IDS: ImageModelMatrix = {
+  google: {
+    small: "gemini-3.1-flash-lite-image",
+    medium: "gemini-3.1-flash-lite-image",
+    large: "gemini-nano-banana-2.1",
+  },
+  // WHY one model id on three tiers: OpenAI prices an image by the tokens it returns, so the tier is the `quality` on the request rather than a different checkpoint.
+
+  // `image.ts` maps tier to quality; the catalog carries the price.
+  openai: {
+    small: "gpt-image-2",
+    medium: "gpt-image-2",
+    large: "gpt-image-2",
+  },
+  // WHY one model on three tiers, and WHY the tier still means something: Agnes
+
+  // prices an image by output resolution, so the tier is the `size` on the request rather than a different checkpoint. `image.ts` maps tier to size.
+
+  // Every tier is currently $0, which is the entire reason this lane exists.
+  agnes: {
+    small: "agnes-image-2.5-flash",
+    medium: "agnes-image-2.5-flash",
+    large: "agnes-image-2.5-flash",
+  },
+};
+
+export const IMAGE_MODEL_CATALOG: Record<ModelId, ImageModelConfig> = {
+  "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,
+  },
+  // Google published 2.1 under one GA id, so there's no preview to pin. If one appears,
+  // the 25 Aug 2026 preview-pinning call moves the sdkId there.
+  "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,
+  },
+  /**
+   * OpenAI's image model, on the Images REST API rather than the chat modality.
+   */
+
+  /*
+   * WHY it is back after being deleted on 1 Sep 2026: it was removed that morning on *"We should never ever use anywhere GPT image."* and asked for again the
+   */
+
+  /*
+   * same afternoon, by name, for the blog hero set.
+   */
+
+  /*
+   * The lane is a capability and the default is a separate question, so the capability returns and `DEFAULT_IMAGE_PROVIDER` stays `google`: nothing draws here unless a caller names `provider: "openai"`.
+   */
+
+  /*
+   * WHY it earns the naming: the Images REST ids are a different and far cheaper product than the chat-modality `openai/gpt-5.4-image-2` that the 31 Aug price ruling was actually about,
+   */
+
+  /*
+   * and the youtube-thumbnail skill's 26 Aug test recorded "excellent tile lighting and a correctly reproduced card" from it.
+   */
+
+  /*
+   * Its one standing ban is narrower and still holds: never a frame carrying a real person's face, because identity drifts across a wall of frames.
+   */
+
+  /*
+   * WHY the price is a floor and not the price: OpenAI bills image output by token ($30 per 1M for this model,
+   */
+
+  /*
+   * off platform.openai.com/docs/pricing on 26 Aug 2026), so what a frame costs depends on its size and its quality.
+   */
+
+  /*
+   * `generateImage` overwrites `priceUsd` with the cost computed from the usage the API returns, and this number is only what a caller sees before that.
+   */
+  "gpt-image-2": {
+    modelId: "gpt-image-2",
+    sdkId: "gpt-image-2",
+    provider: "openai",
+    tier: "medium",
+    pricePerImage: 0.032,
+  },
+  /**
+   * Agnes Image 2.5 Flash, the free image lane, and text-to-image ONLY.
+   */
+
+  /*
+   * WHY the caveat is on the row: it refuses a reference image, measured 9 Sep 2026, and reports that as `403 team not allowed to access model`,
+   */
+
+  /*
+   * which reads as a dead lane rather than a missing capability. `image.ts` refuses a reference before the call so the error says what is true.
+   */
+
+  /*
+   * So this row draws a frame from nothing; anything conditioned on a frame is a gateway call.
+   */
+
+  /*
+   * Ramzi kept it on 9 Sep 2026 for exactly what it is good at: "For the image free lane you can still use Agnes."
+   */
+
+  /*
+   * WHY the price is 0 and the list price is in the comment rather than the field: Agnes publishes $10 / 1,000 images at 1K rising to $24 at 4K,
+   */
+
+  /*
+   * and is charging $0 for every resolution tier and every reference image as a standing promotion (read off wiki.agnes-ai.com/en/docs/pricing, 31 Aug 2026).
+   */
+
+  /*
+   * Recording 0 is what makes a caller's cost report true today; the day the promotion ends this row is the one line to change.
+   */
+
+  /*
+   * WHY it is not routed through a gateway: Cloudflare AI Gateway answers `Invalid provider` for agnes, agnes-ai and agnesai, so there is no gateway route to take.
+   */
+
+  /*
+   * This is a direct lane and it carries its own key.
+   */
+  "agnes-image-2.5-flash": {
+    modelId: "agnes-image-2.5-flash",
+    sdkId: "agnes-image-2.5-flash",
+    provider: "agnes",
+    tier: "medium",
+    pricePerImage: 0,
+  },
+};
+
+/** USD per 1M image output tokens, per model. Used to cost a frame from its usage. */
+export const IMAGE_OUTPUT_TOKEN_PRICE_USD: Record<ModelId, number> = {
+  "gpt-image-2": 30 / 1_000_000,
+};
+
+/** The provider a tier resolves to when the caller names none. */
+export const DEFAULT_IMAGE_PROVIDER: Provider = "google";
+
+/** What an image tier resolves to, for a price or the call itself. */
+export function resolveImageModelConfig(
+  tier: ModelTier,
+  provider: Provider = DEFAULT_IMAGE_PROVIDER,
+): ImageModelConfig {
+  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;
+}
+
+/**
+ * What one frame off `modelId` costs, or null for a model with no published rate.
+ */
+
+/*
+ * A stored frame keeps the price it was drawn at: prices move on a release, so never recompute an old frame's cost from this table.
+ */
+export function imagePriceUsd(modelId: ModelId): number | null {
+  const direct = IMAGE_MODEL_CATALOG[modelId];
+  if (direct) return direct.pricePerImage;
+  // A frame filed under the sdk id it was drawn on (`...-preview`) still has to
+  // price, or the wall shows a blank beside a real cost.
+  return (
+    Object.values(IMAGE_MODEL_CATALOG).find((config) => config.sdkId === modelId)?.pricePerImage ??
+    null
+  );
+}

package/src/analytics/client.test.ts

@@ -0,0 +1,149 @@
+/**
+ * Tests for the browser analytics entrypoint.
+ */
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vite-plus/test";
+
+import { initAnalytics, setProfileId, track, trackRevenue } from "#src/analytics/client.js";
+
+let umamiTrack: ReturnType<typeof vi.fn>;
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  umamiTrack = vi.fn();
+  vi.stubGlobal("window", {
+    umami: { track: umamiTrack, identify: vi.fn() },
+    location: { hostname: "example.com" },
+  });
+  vi.stubGlobal("document", {
+    head: { appendChild: vi.fn() },
+    createElement: () => ({ defer: false, src: "", dataset: {} }),
+    querySelector: () => null,
+  });
+});
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+});
+
+describe("initAnalytics", () => {
+  it("starts tracking once initialized", () => {
+    initAnalytics({
+      websiteId: "w1",
+      host: "https://umami.example.com",
+      autoInjectScript: false,
+    });
+    track("ready");
+    expect(umamiTrack).toHaveBeenCalledWith("ready");
+  });
+
+  it("injects umami script tag with data-* attributes from options", () => {
+    const appendChild = vi.fn();
+    const dataset: Record<string, string> = {};
+    const fakeScript = { defer: false, src: "", dataset } as unknown as HTMLScriptElement;
+    vi.stubGlobal("document", {
+      head: { appendChild },
+      createElement: () => fakeScript,
+      querySelector: () => null,
+    });
+
+    initAnalytics({
+      websiteId: "w-perf",
+      host: "https://umami.example.com",
+      performance: true,
+      tag: "v2",
+      beforeSend: "umamiBeforeSend",
+      domains: ["app.com", "www.app.com"],
+      doNotTrack: true,
+      autoTrack: false,
+      excludeSearch: true,
+      excludeHash: true,
+    });
+
+    expect(appendChild).toHaveBeenCalled();
+    expect(fakeScript.src).toBe("https://umami.example.com/script.js");
+    expect(dataset).toMatchObject({
+      websiteId: "w-perf",
+      performance: "true",
+      tag: "v2",
+      beforeSend: "umamiBeforeSend",
+      domains: "app.com,www.app.com",
+      doNotTrack: "true",
+      autoTrack: "false",
+      excludeSearch: "true",
+      excludeHash: "true",
+    });
+  });
+
+  it("skips tracking entirely when disabled is true", () => {
+    initAnalytics({
+      websiteId: "w1",
+      host: "https://u",
+      disabled: true,
+    });
+    track("anything");
+    expect(umamiTrack).not.toHaveBeenCalled();
+  });
+});
+
+describe("events", () => {
+  it("track() sends the event", async () => {
+    initAnalytics({
+      websiteId: "w1",
+      host: "https://u",
+      autoInjectScript: false,
+    });
+    track("hello", { foo: "bar" });
+    expect(umamiTrack).toHaveBeenCalledWith("hello", { foo: "bar" });
+  });
+
+  it("trackRevenue() forwards value and currency", async () => {
+    initAnalytics({
+      websiteId: "w1",
+      host: "https://u",
+      autoInjectScript: false,
+    });
+    trackRevenue({
+      event: "subscription_started",
+      value: 49,
+      currency: "USD",
+      plan: "pro",
+      transactionId: "sub_abc",
+    });
+    expect(umamiTrack).toHaveBeenCalledWith(
+      "subscription_started",
+      expect.objectContaining({
+        revenue: 49,
+        currency: "USD",
+        plan: "pro",
+        transaction_id: "sub_abc",
+      }),
+    );
+  });
+
+  it("setProfileId() calls identify", async () => {
+    const identify = vi.fn();
+    vi.stubGlobal("window", {
+      umami: { track: umamiTrack, identify },
+      location: { hostname: "example.com" },
+    });
+    initAnalytics({
+      websiteId: "w1",
+      host: "https://u",
+      autoInjectScript: false,
+    });
+    setProfileId("user_123");
+    expect(identify).toHaveBeenCalledWith({ profileId: "user_123" });
+  });
+
+  it("cleanup function stops tracking", () => {
+    const stop = initAnalytics({
+      websiteId: "w1",
+      host: "https://u",
+      autoInjectScript: false,
+    });
+    stop();
+    track("late");
+    expect(umamiTrack).not.toHaveBeenCalled();
+  });
+});