@frockbot/plugin-billing 0.0.0 → 0.3.21

package/frockbot.json

@@ -0,0 +1,28 @@
+{
+  "schemaVersion": 4,
+  "id": "billing",
+  "displayName": "Usage",
+  "version": "0.0.1",
+  "defaultEnablement": "enabled",
+  "compatibility": { "frockbot": ">=0.0.1" },
+  "dependencies": {
+    "flock": ">=0.0.1",
+    "settings": ">=0.0.1",
+    "ui-theme": ">=0.0.1"
+  },
+  "contributions": {
+    "backend": [
+      { "entry": "./user", "host": "user" },
+      { "entry": "./backend", "host": "gateway" }
+    ],
+    "client": {
+      "entry": "./client",
+      "mounts": [
+        { "slot": "frockbot.user-settings-primary-sections", "order": 20 },
+        { "slot": "frockbot.bot-settings-primary-sections", "order": 30 }
+      ],
+      "outlets": []
+    }
+  },
+  "permissions": []
+}

package/package.json

@@ -1,14 +1,49 @@
 {
   "name": "@frockbot/plugin-billing",
-  "version": "0.0.0",
-  "description": "Placeholder reserving this name for trusted publishing. Superseded by the first release.",
-  "license": "UNLICENSED",
+  "version": "0.3.21",
+  "private": false,
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./backend": "./src/backend.ts",
+    "./bot": "./src/bot.ts",
+    "./client": "./src/client/index.ts",
+    "./manifest": "./src/manifest.ts",
+    "./package.json": "./package.json",
+    "./pricing": "./src/pricing.ts",
+    "./shared": "./src/shared.ts",
+    "./store": "./src/store.ts",
+    "./user": "./src/user.ts"
+  },
+  "frockbot": {
+    "manifest": "./frockbot.json"
+  },
+  "scripts": {
+    "test": "bun test src",
+    "typecheck": "vue-tsc --noEmit -p tsconfig.json"
+  },
+  "dependencies": {
+    "@frockbot/client-core": "0.3.21",
+    "@frockbot/client-ui": "0.3.21",
+    "@frockbot/kernel-contracts": "0.3.21",
+    "@frockbot/plugin-flock": "0.3.21",
+    "@frockbot/plugin-shell": "0.3.21",
+    "cordis": "4.0.0-rc.8",
+    "vue": "3.5.41"
+  },
+  "devDependencies": {
+    "@types/bun": "1.4.0",
+    "@vitejs/plugin-vue": "6.0.8",
+    "typescript": "npm:typescript-native-bridge@6.0.3-bridge.16.tsgo.7.0.2",
+    "vite": "8.2.2",
+    "vue-tsc": "3.3.10"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/timoconnellaus/frockbot.git",
     "directory": "packages/plugin-billing"
-  },
-  "publishConfig": {
-    "access": "public"
   }
 }

package/src/backend.ts

@@ -0,0 +1,57 @@
+import { defineGatewayContribution } from "@frockbot/kernel-contracts/contributions";
+import type { Plugin } from "cordis";
+import type { UsageReportV1 } from "./shared.js";
+
+export interface BillingGatewayHostV1 {
+  readUsage(userId: string): Promise<UsageReportV1>;
+}
+
+export interface BillingBackendRouteContributionV1 {
+  packageId: string;
+  route(
+    request: Request,
+    url: URL,
+    context: { userId?: string },
+  ): Promise<Response | undefined>;
+}
+
+export function createBillingBackendContribution(
+  host: BillingGatewayHostV1,
+): BillingBackendRouteContributionV1 {
+  return {
+    packageId: "billing",
+    async route(request, url, context) {
+      if (url.pathname !== "/api/usage" || !context.userId) return undefined;
+      if (request.method !== "GET") {
+        return Response.json({ error: "method not allowed" }, { status: 405 });
+      }
+      try {
+        return Response.json(await host.readUsage(context.userId));
+      } catch (error) {
+        return Response.json(
+          {
+            error: error instanceof Error ? error.message : "usage read failed",
+          },
+          { status: 500 },
+        );
+      }
+    },
+  };
+}
+
+export namespace createBillingBackendContribution {
+  export function plugin(
+    host: BillingGatewayHostV1,
+    lifecycle: { mount(value: BillingBackendRouteContributionV1): () => void },
+  ): Plugin {
+    return () => lifecycle.mount(createBillingBackendContribution(host));
+  }
+}
+
+export const backendContribution = defineGatewayContribution<
+  BillingGatewayHostV1,
+  BillingBackendRouteContributionV1
+>({
+  specifier: "@frockbot/plugin-billing/backend",
+  create: createBillingBackendContribution.plugin,
+});

package/src/bot.test.ts

@@ -0,0 +1,178 @@
+import { describe, expect, test } from "bun:test";
+import type { SessionEvent } from "@frockbot/kernel-contracts";
+import { UsageOutboxV1, usageEntriesFromTurnV1 } from "./bot.js";
+import type { UsageEntryV1 } from "./shared.js";
+
+describe("usage projection", () => {
+  test("prices one bounded entry from each model/usage event in the settled turn", () => {
+    const events = [
+      {
+        type: "model/usage",
+        seq: 4,
+        timestamp: "2026-09-04T01:02:03.000Z",
+        turn: 2,
+        step: 1,
+        requestId: "request-1",
+        provider: "ollama-cloud",
+        model: "glm-5.3-flash:cloud",
+        modelBinding: { connectionId: "ollama-main" },
+        inputTokens: 100,
+        outputTokens: 20,
+        cachedInputTokens: 50,
+        reasoningTokens: 5,
+        latencyMs: 900,
+        estimated: false,
+      },
+      {
+        type: "turn/end",
+        seq: 5,
+        timestamp: "2026-09-04T01:02:04.000Z",
+        turn: 2,
+        outcome: "completed",
+      },
+    ] as SessionEvent[];
+
+    expect(
+      usageEntriesFromTurnV1({
+        botId: "bot-a",
+        runId: "run-a",
+        turn: 2,
+        events,
+      }),
+    ).toEqual([
+      expect.objectContaining({
+        entryId: "bot-a:run-a:request-1",
+        turnId: "run-a:2",
+        bindingId: "ollama-main",
+        inputTokens: 100,
+        cachedInputTokens: 50,
+        costMicros: 19,
+        unknownPrice: false,
+      }),
+    ]);
+  });
+
+  test("keeps entries until an idempotent sink accepts them", async () => {
+    const values = new Map<string, unknown>();
+    const outbox = new UsageOutboxV1({
+      get: (key) => Promise.resolve(values.get(key) as never),
+      put: (key, value) => {
+        values.set(key, value);
+        return Promise.resolve();
+      },
+      delete: (key) => Promise.resolve(values.delete(key)),
+    });
+    const projected = usageEntriesFromTurnV1({
+      botId: "bot-a",
+      runId: "run-a",
+      turn: 2,
+      events: [
+        {
+          type: "model/usage",
+          seq: 1,
+          timestamp: "2026-09-04T01:02:03.000Z",
+          turn: 2,
+          step: 1,
+          requestId: "request-1",
+          provider: "foundation",
+          model: "deterministic-v1",
+          inputTokens: 10,
+          outputTokens: 2,
+          latencyMs: 1,
+          estimated: true,
+        },
+        {
+          type: "turn/end",
+          seq: 2,
+          timestamp: "2026-09-04T01:02:04.000Z",
+          turn: 2,
+          outcome: "completed",
+        },
+      ] as SessionEvent[],
+    });
+    await outbox.append(projected);
+    await expect(
+      outbox.drain({ recordEntries: () => Promise.reject(new Error("away")) }),
+    ).rejects.toThrow("away");
+    expect(await outbox.state()).toMatchObject({ pending: 1 });
+    const delivered: unknown[] = [];
+    await outbox.drain({
+      recordEntries: (entries) => {
+        delivered.push(...entries);
+        return Promise.resolve();
+      },
+    });
+    expect(delivered).toHaveLength(1);
+    expect(await outbox.state()).toMatchObject({ pending: 0 });
+  });
+
+  test("does not project an open Turn and preserves concurrent appends during delivery", async () => {
+    expect(
+      usageEntriesFromTurnV1({
+        botId: "bot-a",
+        runId: "run-open",
+        turn: 1,
+        events: [
+          {
+            type: "model/usage",
+            seq: 1,
+            timestamp: "2026-09-04T01:02:03.000Z",
+            turn: 1,
+            step: 1,
+            requestId: "open-request",
+            provider: "foundation",
+            model: "deterministic-v1",
+            inputTokens: 1,
+            outputTokens: 1,
+            latencyMs: 1,
+            estimated: true,
+          },
+        ] as SessionEvent[],
+      }),
+    ).toEqual([]);
+
+    const values = new Map<string, unknown>();
+    const outbox = new UsageOutboxV1({
+      get: (key) => Promise.resolve(values.get(key) as never),
+      put: (key, value) => {
+        values.set(key, value);
+        return Promise.resolve();
+      },
+      delete: (key) => Promise.resolve(values.delete(key)),
+    });
+    const first = {
+      schemaVersion: 1,
+      entryId: "first",
+      kind: "model",
+      at: "2026-09-04T01:02:03.000Z",
+      provider: "foundation",
+      model: "deterministic-v1",
+      inputTokens: 1,
+      outputTokens: 1,
+      cachedInputTokens: 0,
+      reasoningTokens: 0,
+      voiceSeconds: 0,
+      latencyMs: 1,
+      estimated: false,
+      unknownPrice: false,
+      priceTableVersion: "test",
+      costMicros: 0,
+    } satisfies UsageEntryV1;
+    const second = { ...first, entryId: "second" };
+    await outbox.append([first]);
+    await outbox.drain({
+      recordEntries: async () => {
+        await outbox.append([second]);
+      },
+    });
+    expect(await outbox.state()).toEqual({ pending: 1, truncated: false });
+    const delivered: string[] = [];
+    await outbox.drain({
+      recordEntries: (entries) => {
+        delivered.push(...entries.map((entry) => entry.entryId));
+        return Promise.resolve();
+      },
+    });
+    expect(delivered).toEqual(["second"]);
+  });
+});

package/src/bot.ts

@@ -0,0 +1,157 @@
+import type { SessionEvent } from "@frockbot/kernel-contracts";
+import { modelCostMicrosV1 } from "./pricing.js";
+import {
+  decodeUsageEntryV1,
+  USAGE_OUTBOX_MAX_V1,
+  type UsageEntryV1,
+} from "./shared.js";
+
+export interface UsageSinkV1 {
+  recordEntries(entries: readonly UsageEntryV1[]): Promise<void>;
+}
+
+export function usageEntriesFromTurnV1(input: {
+  botId: string;
+  runId: string;
+  turn: number;
+  events: readonly SessionEvent[];
+}): UsageEntryV1[] {
+  if (
+    !input.events.some(
+      (event) => event.type === "turn/end" && event.turn === input.turn,
+    )
+  ) {
+    return [];
+  }
+  return input.events.flatMap((event) => {
+    if (event.type !== "model/usage" || event.turn !== input.turn) return [];
+    const priced = modelCostMicrosV1(event.provider, event.model, event);
+    return [
+      {
+        schemaVersion: 1,
+        entryId: `${input.botId}:${input.runId}:${event.requestId}`,
+        kind: "model",
+        botId: input.botId,
+        runId: input.runId,
+        turnId: `${input.runId}:${input.turn}`,
+        turn: input.turn,
+        requestId: event.requestId,
+        at: event.timestamp,
+        provider: event.provider,
+        model: event.model,
+        ...(event.modelBinding
+          ? { bindingId: event.modelBinding.connectionId }
+          : {}),
+        inputTokens: event.inputTokens,
+        outputTokens: event.outputTokens,
+        cachedInputTokens: event.cachedInputTokens ?? 0,
+        reasoningTokens: event.reasoningTokens ?? 0,
+        voiceSeconds: 0,
+        latencyMs: event.latencyMs,
+        estimated: event.estimated,
+        unknownPrice: priced.unknown,
+        priceTableVersion: priced.priceTableVersion,
+        costMicros: priced.costMicros,
+      },
+    ];
+  });
+}
+
+export const USAGE_OUTBOX_KEY_V1 = "billing:usage-outbox";
+
+export interface UsageOutboxStorageV1 {
+  get<T>(key: string): Promise<T | undefined>;
+  put<T>(key: string, value: T): Promise<void>;
+  delete(key: string): Promise<boolean>;
+}
+
+interface StoredUsageOutboxV1 {
+  schemaVersion: 1;
+  entries: UsageEntryV1[];
+  truncated: boolean;
+}
+
+function decodeOutboxV1(value: unknown): StoredUsageOutboxV1 {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return { schemaVersion: 1, entries: [], truncated: false };
+  }
+  const candidate = value as Partial<StoredUsageOutboxV1>;
+  if (candidate.schemaVersion !== 1 || !Array.isArray(candidate.entries)) {
+    return { schemaVersion: 1, entries: [], truncated: true };
+  }
+  const entries: UsageEntryV1[] = [];
+  for (const entry of candidate.entries.slice(-USAGE_OUTBOX_MAX_V1)) {
+    try {
+      entries.push(decodeUsageEntryV1(entry));
+    } catch {
+      // A bad derived entry is dropped while the durable model/usage event
+      // remains rebuildable; the marker makes the gap visible.
+    }
+  }
+  return {
+    schemaVersion: 1,
+    entries,
+    truncated:
+      candidate.truncated === true ||
+      candidate.entries.length !== entries.length,
+  };
+}
+
+export class UsageOutboxV1 {
+  private readonly maximum: number;
+
+  constructor(
+    private readonly storage: UsageOutboxStorageV1,
+    options: { maximum?: number } = {},
+  ) {
+    this.maximum = options.maximum ?? USAGE_OUTBOX_MAX_V1;
+  }
+
+  private async read(): Promise<StoredUsageOutboxV1> {
+    return decodeOutboxV1(await this.storage.get<unknown>(USAGE_OUTBOX_KEY_V1));
+  }
+
+  private async write(outbox: StoredUsageOutboxV1): Promise<void> {
+    if (outbox.entries.length === 0 && !outbox.truncated) {
+      await this.storage.delete(USAGE_OUTBOX_KEY_V1);
+      return;
+    }
+    await this.storage.put(USAGE_OUTBOX_KEY_V1, outbox);
+  }
+
+  async append(entries: readonly UsageEntryV1[]): Promise<void> {
+    if (entries.length === 0) return;
+    const stored = await this.read();
+    const seen = new Set(stored.entries.map((entry) => entry.entryId));
+    for (const candidate of entries) {
+      const entry = decodeUsageEntryV1(candidate);
+      if (seen.has(entry.entryId)) continue;
+      seen.add(entry.entryId);
+      stored.entries.push(entry);
+    }
+    if (stored.entries.length > this.maximum) {
+      stored.entries = stored.entries.slice(-this.maximum);
+      stored.truncated = true;
+    }
+    await this.write(stored);
+  }
+
+  async drain(sink: UsageSinkV1): Promise<void> {
+    const stored = await this.read();
+    if (stored.entries.length === 0) return;
+    await sink.recordEntries(stored.entries);
+    const delivered = new Set(stored.entries.map((entry) => entry.entryId));
+    const current = await this.read();
+    await this.write({
+      schemaVersion: 1,
+      entries: current.entries.filter((entry) => !delivered.has(entry.entryId)),
+      // A successful delivery does not repair an earlier bounded loss.
+      truncated: current.truncated || stored.truncated,
+    });
+  }
+
+  async state(): Promise<{ pending: number; truncated: boolean }> {
+    const stored = await this.read();
+    return { pending: stored.entries.length, truncated: stored.truncated };
+  }
+}

package/src/client/BotSpendLine.vue

@@ -0,0 +1,49 @@
+<script setup lang="ts">
+import { frockBotWebDataKey } from "@frockbot/plugin-shell/shared";
+import { computed, inject, onMounted } from "vue";
+import { formatCostV1 } from "./format.js";
+import { usageStateKey } from "./state.js";
+
+const providedUsage = inject(usageStateKey);
+const providedWeb = inject(frockBotWebDataKey);
+if (!providedUsage || !providedWeb) {
+  throw new Error("usage client services were not provided");
+}
+const usage = providedUsage;
+const web = providedWeb;
+const cost = computed(
+  () =>
+    usage.value.report?.bots.find((row) => row.id === web.value.activeBotId)
+      ?.costMicros ?? 0,
+);
+
+onMounted(() => {
+  if (!usage.value.loaded && !usage.value.busy) void usage.value.load();
+});
+</script>
+
+<template>
+  <p class="bot-spend">
+    <span>This month's spend</span>
+    <strong>{{ formatCostV1(cost) }}</strong>
+  </p>
+</template>
+
+<style scoped>
+.bot-spend {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--frock-radius-control);
+  margin: 0;
+  padding: var(--frock-radius-control) var(--frock-radius-card);
+  border-radius: var(--frock-radius-control);
+  color: var(--frock-text-muted);
+  background: var(--frock-surface-subtle);
+  font-size: var(--frock-text-sm);
+}
+
+.bot-spend strong {
+  color: var(--frock-text);
+}
+</style>