@frockbot/plugin-billing 0.0.0 → 0.3.20

package/src/client/UsageSection.vue

@@ -0,0 +1,191 @@
+<script setup lang="ts">
+import { flockWebDataKey } from "@frockbot/plugin-flock/client/state";
+import { computed, inject, onMounted } from "vue";
+import { formatCostV1, shortModelNameV1 } from "./format.js";
+import { usageStateKey } from "./state.js";
+
+const providedUsage = inject(usageStateKey);
+const providedFlock = inject(flockWebDataKey);
+if (!providedUsage || !providedFlock) {
+  throw new Error("usage client services were not provided");
+}
+const usage = providedUsage;
+const flock = providedFlock;
+
+const maximumDayCost = computed(() =>
+  Math.max(1, ...(usage.value.report?.days.map((day) => day.costMicros) ?? [])),
+);
+
+function botName(botId: string): string {
+  return flock.value.profiles[botId]?.name ?? botId;
+}
+
+function barWidth(costMicros: number): string {
+  return `${Math.round((costMicros / maximumDayCost.value) * 100)}%`;
+}
+
+onMounted(() => void usage.value.load());
+</script>
+
+<template>
+  <section class="usage-card" aria-labelledby="usage-heading">
+    <header class="usage-card__header">
+      <div>
+        <h2 id="usage-heading">Usage</h2>
+        <p>This month</p>
+      </div>
+      <strong class="usage-card__total">
+        {{ formatCostV1(usage.report?.currentMonthCostMicros ?? 0) }}
+      </strong>
+    </header>
+
+    <p v-if="usage.error" class="usage-card__error" role="alert">
+      {{ usage.error }}
+    </p>
+    <p v-else-if="usage.busy && !usage.loaded" class="usage-card__quiet">
+      Loading usage…
+    </p>
+    <template v-else-if="usage.report">
+      <div class="usage-card__columns">
+        <section>
+          <h3>By Bot</h3>
+          <p v-if="usage.report.bots.length === 0" class="usage-card__quiet">
+            No spend yet this month.
+          </p>
+          <ul v-else class="usage-list">
+            <li v-for="row in usage.report.bots" :key="row.id">
+              <span>{{ botName(row.id) }}</span>
+              <strong>{{ formatCostV1(row.costMicros) }}</strong>
+            </li>
+          </ul>
+        </section>
+        <section>
+          <h3>By model</h3>
+          <p v-if="usage.report.models.length === 0" class="usage-card__quiet">
+            No model spend yet this month.
+          </p>
+          <ul v-else class="usage-list">
+            <li v-for="row in usage.report.models" :key="row.id">
+              <span>{{ shortModelNameV1(row.id) }}</span>
+              <strong>{{ formatCostV1(row.costMicros) }}</strong>
+            </li>
+          </ul>
+        </section>
+      </div>
+
+      <section>
+        <h3>Last 30 days</h3>
+        <ol class="usage-days">
+          <li v-for="day in usage.report.days" :key="day.day">
+            <time :datetime="day.day">{{ day.day.slice(5) }}</time>
+            <span class="usage-days__track" aria-hidden="true">
+              <span
+                class="usage-days__bar"
+                :style="{ width: barWidth(day.costMicros) }"
+              />
+            </span>
+            <span>{{ formatCostV1(day.costMicros) }}</span>
+          </li>
+        </ol>
+      </section>
+      <p
+        v-if="usage.report.estimatedCalls || usage.report.unknownPriceCalls"
+        class="usage-card__quiet"
+      >
+        Some totals use estimates because exact usage or pricing was not
+        available.
+      </p>
+    </template>
+  </section>
+</template>
+
+<style scoped>
+.usage-card {
+  display: flex;
+  flex-direction: column;
+  gap: var(--frock-radius-card);
+  padding: var(--frock-radius-card);
+  border-radius: var(--frock-radius-card);
+  background: var(--frock-surface-subtle);
+}
+
+.usage-card__header,
+.usage-list li,
+.usage-days li {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--frock-radius-control);
+}
+
+.usage-card h2,
+.usage-card h3,
+.usage-card p,
+.usage-list,
+.usage-days {
+  margin: 0;
+}
+
+.usage-card h2 {
+  font-size: var(--frock-text-xl);
+}
+
+.usage-card h3 {
+  margin-bottom: var(--frock-radius-control);
+  font-size: var(--frock-text-sm);
+  text-transform: uppercase;
+  letter-spacing: var(--frock-tracking-eyebrow);
+}
+
+.usage-card__header p,
+.usage-card__quiet {
+  color: var(--frock-text-muted);
+  font-size: var(--frock-text-sm);
+}
+
+.usage-card__total {
+  font-size: var(--frock-text-display);
+  font-family: var(--frock-font-display);
+}
+
+.usage-card__columns {
+  display: grid;
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+  gap: var(--frock-radius-card);
+}
+
+.usage-list,
+.usage-days {
+  display: flex;
+  flex-direction: column;
+  gap: calc(var(--frock-radius-control) / 2);
+  padding: 0;
+  list-style: none;
+  font-size: var(--frock-text-sm);
+}
+
+.usage-days time {
+  color: var(--frock-text-muted);
+  font-family: var(--frock-font-mono);
+}
+
+.usage-days__track {
+  flex: 1;
+  height: calc(var(--frock-icon-sm) / 2);
+  overflow: hidden;
+  border-radius: var(--frock-radius-control);
+  background: var(--frock-surface-raised);
+}
+
+.usage-days__bar {
+  display: block;
+  height: 100%;
+  border-radius: inherit;
+  background: var(--frock-action-primary);
+}
+
+.usage-card__error {
+  color: var(--frock-danger-text);
+  font-size: var(--frock-text-sm);
+}
+</style>

package/src/client/format.ts

@@ -0,0 +1,13 @@
+export function formatCostV1(costMicros: number): string {
+  return new Intl.NumberFormat("en", {
+    style: "currency",
+    currency: "USD",
+    minimumFractionDigits: 2,
+    maximumFractionDigits: 2,
+  }).format(costMicros / 1_000_000);
+}
+
+export function shortModelNameV1(value: string): string {
+  const slash = value.indexOf("/");
+  return slash < 0 ? value : value.slice(slash + 1);
+}

package/src/client/index.test.ts

@@ -0,0 +1,92 @@
+import { describe, expect, test } from "bun:test";
+import type {
+  ClientPluginContext,
+  ClientSlotRegistration,
+} from "@frockbot/client-core";
+import { billingClientPlugin } from "./index.js";
+import { formatCostV1, shortModelNameV1 } from "./format.js";
+import { usageStateKey, type UsageClientStateV1 } from "./state.js";
+
+const REPORT = {
+  schemaVersion: 1,
+  month: "2026-09",
+  currentMonthCostMicros: 1_250_000,
+  lifetimeCostMicros: 2_000_000,
+  currentMonthInputTokens: 100,
+  currentMonthOutputTokens: 20,
+  currentMonthVoiceSeconds: 30,
+  estimatedCalls: 1,
+  unknownPriceCalls: 0,
+  bots: [
+    {
+      id: "bot-a",
+      costMicros: 1_250_000,
+      inputTokens: 100,
+      outputTokens: 20,
+      voiceSeconds: 0,
+      estimatedCalls: 1,
+      unknownPriceCalls: 0,
+    },
+  ],
+  models: [],
+  days: Array.from({ length: 30 }, (_, offset) => ({
+    day: `2026-09-${String(offset + 1).padStart(2, "0")}`,
+    costMicros: offset,
+  })),
+};
+
+function mount(): {
+  state: { value: UsageClientStateV1 };
+  slots: ClientSlotRegistration[];
+  calls: string[];
+} {
+  const slots: ClientSlotRegistration[] = [];
+  const calls: string[] = [];
+  let state: unknown;
+  const context: ClientPluginContext = {
+    transport: {
+      turn: () => Promise.resolve({ runId: "run", text: "", events: [] }),
+      hostedRequest: (path) => {
+        calls.push(path);
+        return Promise.resolve(REPORT);
+      },
+    },
+    inject: () => {
+      throw new Error("unexpected client provider");
+    },
+    provide: (key, value) => {
+      if (key === usageStateKey) state = value;
+      return () => {};
+    },
+    slot: (registration) => {
+      slots.push(registration);
+      return () => slots.splice(slots.indexOf(registration), 1);
+    },
+  };
+  billingClientPlugin(context);
+  return { state: state as { value: UsageClientStateV1 }, slots, calls };
+}
+
+describe("billing client contribution", () => {
+  test("mounts the account report and per-Bot line in Settings", () => {
+    expect(mount().slots.map((slot) => slot.slot)).toEqual([
+      "frockbot.user-settings-primary-sections",
+      "frockbot.bot-settings-primary-sections",
+    ]);
+  });
+
+  test("loads and decodes the Usage report", async () => {
+    const mounted = mount();
+    await mounted.state.value.load();
+    expect(mounted.calls).toEqual(["/api/usage"]);
+    expect(mounted.state.value.report?.currentMonthCostMicros).toBe(1_250_000);
+    expect(mounted.state.value.report?.bots[0]?.id).toBe("bot-a");
+  });
+
+  test("formats dollars and compact model names for the rendered view", () => {
+    expect(formatCostV1(1_250_000)).toBe("$1.25");
+    expect(shortModelNameV1("ollama-cloud/glm-5.3-flash:cloud")).toBe(
+      "glm-5.3-flash:cloud",
+    );
+  });
+});

package/src/client/index.ts

@@ -0,0 +1,56 @@
+/// <reference path="../env.d.ts" />
+
+import type { ClientPlugin } from "@frockbot/client-core";
+import { defineClientContribution } from "@frockbot/kernel-contracts/contributions";
+import { ref } from "vue";
+import { decodeUsageReportV1 } from "../shared.js";
+import BotSpendLine from "./BotSpendLine.vue";
+import UsageSection from "./UsageSection.vue";
+import { usageStateKey, type UsageClientStateV1 } from "./state.js";
+
+export const billingClientPlugin: ClientPlugin = (ctx) => {
+  const state = ref<UsageClientStateV1>({
+    loaded: false,
+    busy: false,
+    async load() {
+      if (!ctx.transport.hostedRequest) {
+        state.value.error = "Usage is unavailable on this client";
+        return;
+      }
+      state.value.busy = true;
+      try {
+        state.value.report = decodeUsageReportV1(
+          await ctx.transport.hostedRequest("/api/usage"),
+        );
+        state.value.loaded = true;
+        state.value.error = undefined;
+      } catch (error) {
+        state.value.error =
+          error instanceof Error ? error.message : "Could not load usage";
+      } finally {
+        state.value.busy = false;
+      }
+    },
+  });
+
+  return [
+    ctx.provide(usageStateKey, state),
+    ctx.slot({
+      slot: "frockbot.user-settings-primary-sections",
+      order: 20,
+      component: UsageSection,
+    }),
+    ctx.slot({
+      slot: "frockbot.bot-settings-primary-sections",
+      order: 30,
+      component: BotSpendLine,
+    }),
+  ];
+};
+
+export default billingClientPlugin;
+
+export const clientContribution = defineClientContribution<ClientPlugin>({
+  specifier: "@frockbot/plugin-billing/client",
+  plugin: billingClientPlugin,
+});

package/src/client/state.ts

@@ -0,0 +1,13 @@
+import type { InjectionKey, Ref } from "vue";
+import type { UsageReportV1 } from "../shared.js";
+
+export interface UsageClientStateV1 {
+  report?: UsageReportV1;
+  loaded: boolean;
+  busy: boolean;
+  error?: string;
+  load(): Promise<void>;
+}
+
+export const usageStateKey: InjectionKey<Ref<UsageClientStateV1>> =
+  Symbol("usage-state");

package/src/env.d.ts

@@ -0,0 +1,6 @@
+declare module "*.vue" {
+  import type { DefineComponent } from "vue";
+
+  const component: DefineComponent;
+  export default component;
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+export * from "./bot.js";
+export * from "./pricing.js";
+export * from "./shared.js";
+export * from "./store.js";
+export { default as manifest } from "./manifest.js";

package/src/manifest.ts

@@ -0,0 +1,3 @@
+import manifest from "../frockbot.json" with { type: "json" };
+
+export default manifest;

package/src/pricing.test.ts

@@ -0,0 +1,56 @@
+import { describe, expect, test } from "bun:test";
+import {
+  MODEL_PRICE_TABLE_VERSION_V1,
+  modelCostMicrosV1,
+  resolveModelPriceV1,
+  voiceCostMicrosV1,
+  voiceIncrementCostMicrosV1,
+} from "./pricing.js";
+
+describe("billing prices", () => {
+  test("prices cached and uncached tokens without double-counting reasoning", () => {
+    expect(
+      modelCostMicrosV1(
+        "flock-ai",
+        "@frock/deepseek-ai/deepseek-v4-flash-0731",
+        {
+          inputTokens: 1_000_000,
+          cachedInputTokens: 250_000,
+          outputTokens: 100_000,
+          reasoningTokens: 50_000,
+        },
+      ),
+    ).toMatchObject({
+      costMicros: 465_500,
+      unknown: false,
+      priceTableVersion: MODEL_PRICE_TABLE_VERSION_V1,
+    });
+  });
+
+  test("normalizes Ollama cloud suffixes", () => {
+    expect(
+      resolveModelPriceV1("ollama-cloud", "glm-5.3-flash:cloud"),
+    ).toMatchObject({ unknown: false });
+  });
+
+  test("uses and flags the conservative unknown-model rate", () => {
+    expect(
+      modelCostMicrosV1("private-provider", "new-model", {
+        inputTokens: 10,
+        outputTokens: 2,
+      }),
+    ).toMatchObject({ costMicros: 200, unknown: true });
+  });
+
+  test("prices voice by recorded duration", () => {
+    expect(voiceCostMicrosV1(90)).toBe(25_500);
+  });
+
+  test("prices cumulative voice increments without report-frequency drift", () => {
+    expect(
+      voiceIncrementCostMicrosV1(1, 1) +
+        voiceIncrementCostMicrosV1(2, 1) +
+        voiceIncrementCostMicrosV1(3, 1),
+    ).toBe(voiceCostMicrosV1(3));
+  });
+});

package/src/pricing.ts

@@ -0,0 +1,176 @@
+import type { LlmUsageV1 } from "@frockbot/kernel-contracts";
+
+/** Immutable price snapshot used by every entry written by this release. */
+export const MODEL_PRICE_TABLE_VERSION_V1 = "2026-09-04";
+
+/** Platform markup. One means the User sees provider cost with no markup. */
+export const PLATFORM_COST_MULTIPLIER_V1 = 1;
+
+/** A deliberately conservative fallback for a model absent from the table. */
+export const UNKNOWN_MODEL_PRICE_V1 = {
+  inputUsdPerMillion: 10,
+  cachedInputUsdPerMillion: 10,
+  outputUsdPerMillion: 50,
+} as const;
+
+export interface ModelPriceV1 {
+  provider: string;
+  model: string;
+  inputUsdPerMillion: number;
+  cachedInputUsdPerMillion?: number;
+  outputUsdPerMillion: number;
+  sourceUrl: string;
+}
+
+const OPENAI_SOURCE = "https://developers.openai.com/api/docs/models/compare";
+const CLOUDFLARE_SOURCE =
+  "https://developers.cloudflare.com/workers-ai/platform/pricing/";
+const OLLAMA_SOURCE = "https://ollama.com/cloud";
+
+/**
+ * Provider/model prices in dollars per million tokens.
+ *
+ * Ollama's two DeepSeek models use its published peak prices so a static
+ * ledger never understates a request made during the peak window.
+ */
+export const MODEL_PRICE_TABLE_V1: readonly ModelPriceV1[] = [
+  {
+    provider: "foundation",
+    model: "deterministic-v1",
+    inputUsdPerMillion: 0,
+    cachedInputUsdPerMillion: 0,
+    outputUsdPerMillion: 0,
+    sourceUrl: "https://github.com/timoconnellaus/frockbot",
+  },
+  {
+    provider: "flock-ai",
+    model: "@frock/deepseek-ai/deepseek-v4-flash-0731",
+    inputUsdPerMillion: 0.44,
+    cachedInputUsdPerMillion: 0.014,
+    outputUsdPerMillion: 1.32,
+    sourceUrl: CLOUDFLARE_SOURCE,
+  },
+  ...[
+    ["gpt-6-astra", 10, 1, 50],
+    ["gpt-5.6", 4, 0.4, 20],
+    ["gpt-5.6-sol", 4, 0.4, 20],
+    ["gpt-5.6-terra", 2, 0.2, 12],
+    ["gpt-5.6-luna", 0.2, 0.02, 1.2],
+  ].map(([model, input, cached, output]) => ({
+    provider: "openai-compatible",
+    model: String(model),
+    inputUsdPerMillion: Number(input),
+    cachedInputUsdPerMillion: Number(cached),
+    outputUsdPerMillion: Number(output),
+    sourceUrl: OPENAI_SOURCE,
+  })),
+  ...[
+    ["deepseek-v4-flash", 0.44, 0.014, 1.32],
+    ["deepseek-v4-pro", 1.32, 0.044, 3.96],
+    ["gemma4", 0.14, 0.05, 0.4],
+    ["glm-5.3", 1.4, 0.26, 4.4],
+    ["glm-5.3-flash", 0.15, 0.03, 0.5],
+    ["glm-5.2", 1.4, 0.26, 4.4],
+    ["glm-5.1", 1, 0.2, 3.2],
+    ["gpt-oss:120b", 0.15, 0.014, 0.6],
+    ["gpt-oss:20b", 0.07, 0.035, 0.3],
+    ["kimi-k3", 3, 0.3, 15],
+    ["kimi-k2.7-code", 0.95, 0.19, 4],
+    ["kimi-k2.6", 0.95, 0.16, 4],
+    ["minimax-m3", 0.6, 0.12, 2.4],
+    ["minimax-m2.7", 0.3, 0.06, 1.2],
+    ["mistral-large-3", 0.5, 0.5, 1.5],
+    ["qwen3.5:397b", 0.6, 0.6, 3.6],
+  ].map(([model, input, cached, output]) => ({
+    provider: "ollama-cloud",
+    model: String(model),
+    inputUsdPerMillion: Number(input),
+    cachedInputUsdPerMillion: Number(cached),
+    outputUsdPerMillion: Number(output),
+    sourceUrl: OLLAMA_SOURCE,
+  })),
+] as const;
+
+export interface ResolvedModelPriceV1 {
+  price: Omit<ModelPriceV1, "provider" | "model" | "sourceUrl">;
+  unknown: boolean;
+  priceTableVersion: string;
+}
+
+function canonicalModelV1(provider: string, model: string): string {
+  if (provider === "ollama-cloud") return model.replace(/:cloud$/, "");
+  if (provider === "flock-ai" && model.startsWith("@flock/")) {
+    return `@frock/${model.slice("@flock/".length)}`;
+  }
+  return model;
+}
+
+export function resolveModelPriceV1(
+  provider: string,
+  model: string,
+): ResolvedModelPriceV1 {
+  const canonical = canonicalModelV1(provider, model);
+  const found = MODEL_PRICE_TABLE_V1.find(
+    (entry) => entry.provider === provider && entry.model === canonical,
+  );
+  const price = found ?? UNKNOWN_MODEL_PRICE_V1;
+  return {
+    price: {
+      inputUsdPerMillion: price.inputUsdPerMillion,
+      ...(price.cachedInputUsdPerMillion === undefined
+        ? {}
+        : { cachedInputUsdPerMillion: price.cachedInputUsdPerMillion }),
+      outputUsdPerMillion: price.outputUsdPerMillion,
+    },
+    unknown: found === undefined,
+    priceTableVersion: MODEL_PRICE_TABLE_VERSION_V1,
+  };
+}
+
+/** One micro-dollar is one millionth of a dollar. */
+export function modelCostMicrosV1(
+  provider: string,
+  model: string,
+  usage: LlmUsageV1,
+): ResolvedModelPriceV1 & { costMicros: number } {
+  const resolved = resolveModelPriceV1(provider, model);
+  const cached = Math.min(usage.cachedInputTokens ?? 0, usage.inputTokens);
+  const uncached = usage.inputTokens - cached;
+  const cost =
+    uncached * resolved.price.inputUsdPerMillion +
+    cached *
+      (resolved.price.cachedInputUsdPerMillion ??
+        resolved.price.inputUsdPerMillion) +
+    usage.outputTokens * resolved.price.outputUsdPerMillion;
+  return {
+    ...resolved,
+    costMicros: Math.round(cost * PLATFORM_COST_MULTIPLIER_V1),
+  };
+}
+
+/** OpenAI's published realtime transcription price, billed by duration. */
+export const VOICE_USD_PER_MINUTE_V1 = 0.017;
+export const VOICE_PRICE_SOURCE_V1 =
+  "https://developers.openai.com/api/docs/models/gpt-live-transcribe";
+
+export function voiceCostMicrosV1(seconds: number): number {
+  return Math.round(
+    (seconds / 60) *
+      VOICE_USD_PER_MINUTE_V1 *
+      1_000_000 *
+      PLATFORM_COST_MULTIPLIER_V1,
+  );
+}
+
+/**
+ * Prices one cumulative voice receipt without making the result depend on how
+ * often the session reported. The sum of every increment therefore equals the
+ * rounded price of the final cumulative duration.
+ */
+export function voiceIncrementCostMicrosV1(
+  sessionSeconds: number,
+  recordedSeconds: number,
+): number {
+  const previousSeconds = sessionSeconds - recordedSeconds;
+  return voiceCostMicrosV1(sessionSeconds) - voiceCostMicrosV1(previousSeconds);
+}