@agent-finops/core 0.8.0 → 0.9.0

package/dist/resultCard.d.ts

@@ -0,0 +1,350 @@
+import { z } from "zod";
+import type { DetectedPlan } from "./planDetection.js";
+import type { UsageRecord } from "./schema.js";
+/**
+ * The canonical result card (`aibill.result_card` v1) — C-lane design §1.1.
+ *
+ * ONE contract behind every money surface (CLI default card, --full header,
+ * MCP `resultCard`, statusline expansion): per-subscription rows with
+ * per-basis figures, then a labeled totals stack that is NEVER blended into
+ * one number. Three kinds of money exist and they are never added together:
+ *
+ *  - committed  (`subscription_committed`): the list price of a detected
+ *    plan. A fact about price, not usage. Never `~`.
+ *  - API-equivalent value (`api_equivalent`): usage × published API rates.
+ *    Estimated. Never billed. `~` appears on EVERY figure of this basis and
+ *    on NO other basis.
+ *  - billed (`provider_billed`): provider-reported AND verified. Exact
+ *    digits, never `~`, never compacted.
+ *
+ * `detectedUnverifiedUsd` is disclosure-only: provider-reported dollars from
+ * a connector that is not yet live-verified (cursor today). It joins NO
+ * total, is never "billed", never "~", and renders only in Evidence lines
+ * and MCP output. It graduates to `billed` the day the connector is
+ * live-verified.
+ */
+export type ResultCardBasis = "subscription_committed" | "api_equivalent" | "provider_billed";
+export type ResultCardMode = "local-logs" | "connected" | "mixed" | "demo";
+export type ResultCardRunway = {
+    kind: "five-hour" | "weekly";
+    remainingPercent: number;
+    resetsAt: string;
+};
+export type ResultCardSubscriptionRow = {
+    /** Display id; "chatgpt" covers the codex agent. */
+    id: "claude" | "chatgpt" | "cursor" | string;
+    agentId: "claude-code" | "codex" | null;
+    /** "Max 5x", "Pro"; null = plan not detected/priced. */
+    planLabel: string | null;
+    connection: "local_logs" | "connected" | "detected_only";
+    committedUsdPerMonth: number | null;
+    apiEquivalentUsd: number | null;
+    providerBilledUsd: number | null;
+    /**
+     * Provider-reported dollars a beta/unverified connector returned (cursor
+     * today). Disclosure only: rendered in the Evidence line and MCP; NEVER in
+     * rows' money columns, NEVER totaled, never "billed", never "~".
+     */
+    detectedUnverifiedUsd: number | null;
+    /** 0-2 FRESH limits, most-urgent first; single-limit renderers take [0]. */
+    runways: ResultCardRunway[];
+};
+export type ResultCardTotals = {
+    subscriptionCommitted: {
+        amountUsd: number | null;
+        pricedSubs: number;
+        totalSubs: number;
+    };
+    /** "missing" ⟺ amountUsd null. */
+    apiEquivalent: {
+        amountUsd: number | null;
+        financialEvidence: "estimated" | "missing";
+    };
+    /** "missing" ⟺ amountUsd null. */
+    providerBilled: {
+        amountUsd: number | null;
+        financialEvidence: "verified" | "missing";
+    };
+    /** Reserved and PERMANENTLY null — see blendPolicy. */
+    blended: null;
+    /**
+     * String constant; survives null-stripping serializers as the
+     * machine-readable statement of the no-blend rule.
+     */
+    blendPolicy: "never_blended";
+};
+export type ResultCardByProjectRow = {
+    project: string;
+    amountUsd: number;
+    /** Unrounded-fraction share (4-dp, largest-remainder; sums to 1.0000). */
+    share: number;
+    unattributed: boolean;
+};
+export type ResultCardByProjectBlock = {
+    /** The card's primary basis, stated once. */
+    basis: "api_equivalent" | "provider_billed";
+    rows: ResultCardByProjectRow[];
+    /** null when it would cover 0 projects — never a $0.00 (0% · 0 projects) row. */
+    everythingElse: {
+        amountUsd: number;
+        share: number;
+        projectCount: number;
+    } | null;
+};
+export type ResultCard = {
+    kind: "aibill.result_card";
+    schemaVersion: 1;
+    currency: "USD";
+    /** Evidence window (default 30). */
+    windowDays: number;
+    mode: ResultCardMode;
+    /** Stable order: claude, chatgpt/codex, cursor, then others alphabetical. */
+    subscriptions: ResultCardSubscriptionRow[];
+    /** The labeled stack — NEVER one blended figure. */
+    totals: ResultCardTotals;
+    /** null when zero attributable rows (never a $0 row). */
+    byProject: ResultCardByProjectBlock | null;
+};
+/** §1.2 canonical vocabulary — everything outside this set is killed. */
+export declare const resultCardVocabulary: Readonly<{
+    readonly committed: "committed";
+    /** Sanctioned narrow alias for the committed total, statusline <75 col only. */
+    readonly committedNarrowAlias: "subs";
+    readonly apiEquivalent: "API-equivalent";
+    readonly billed: "billed";
+    readonly estimatedMarker: "~";
+    readonly notReported: "not reported";
+    readonly notReportedShort: "n/r";
+    readonly notReportedLegend: "n/r = not reported";
+    readonly estimatedMarkerLegend: "~ = estimated at API rates";
+    readonly everythingElse: "everything else";
+    readonly unattributed: "unattributed";
+    readonly detectedUnverifiedSuffix: "detected (unverified · beta connector)";
+    readonly blendPolicy: "never_blended";
+}>;
+/**
+ * Killed on sight (§1.2): QA greps new/changed rendered copy for these.
+ * "provider-reported" survives ONLY in trust/mode lines explaining where
+ * `billed` comes from — never on a figure.
+ */
+export declare const resultCardKilledTerms: readonly string[];
+export declare const resultCardRunwaySchema: z.ZodObject<{
+    kind: z.ZodEnum<{
+        "five-hour": "five-hour";
+        weekly: "weekly";
+    }>;
+    remainingPercent: z.ZodNumber;
+    resetsAt: z.ZodString;
+}, z.core.$strict>;
+export declare const resultCardSubscriptionRowSchema: z.ZodObject<{
+    id: z.ZodString;
+    agentId: z.ZodNullable<z.ZodEnum<{
+        "claude-code": "claude-code";
+        codex: "codex";
+    }>>;
+    planLabel: z.ZodNullable<z.ZodString>;
+    connection: z.ZodEnum<{
+        connected: "connected";
+        local_logs: "local_logs";
+        detected_only: "detected_only";
+    }>;
+    committedUsdPerMonth: z.ZodNullable<z.ZodNumber>;
+    apiEquivalentUsd: z.ZodNullable<z.ZodNumber>;
+    providerBilledUsd: z.ZodNullable<z.ZodNumber>;
+    detectedUnverifiedUsd: z.ZodNullable<z.ZodNumber>;
+    runways: z.ZodArray<z.ZodObject<{
+        kind: z.ZodEnum<{
+            "five-hour": "five-hour";
+            weekly: "weekly";
+        }>;
+        remainingPercent: z.ZodNumber;
+        resetsAt: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export declare const resultCardTotalsSchema: z.ZodObject<{
+    subscriptionCommitted: z.ZodObject<{
+        amountUsd: z.ZodNullable<z.ZodNumber>;
+        pricedSubs: z.ZodNumber;
+        totalSubs: z.ZodNumber;
+    }, z.core.$strict>;
+    apiEquivalent: z.ZodObject<{
+        amountUsd: z.ZodNullable<z.ZodNumber>;
+        financialEvidence: z.ZodEnum<{
+            estimated: "estimated";
+            missing: "missing";
+        }>;
+    }, z.core.$strict>;
+    providerBilled: z.ZodObject<{
+        amountUsd: z.ZodNullable<z.ZodNumber>;
+        financialEvidence: z.ZodEnum<{
+            verified: "verified";
+            missing: "missing";
+        }>;
+    }, z.core.$strict>;
+    blended: z.ZodNull;
+    blendPolicy: z.ZodLiteral<"never_blended">;
+}, z.core.$strict>;
+export declare const resultCardByProjectSchema: z.ZodObject<{
+    basis: z.ZodEnum<{
+        provider_billed: "provider_billed";
+        api_equivalent: "api_equivalent";
+    }>;
+    rows: z.ZodArray<z.ZodObject<{
+        project: z.ZodString;
+        amountUsd: z.ZodNumber;
+        share: z.ZodNumber;
+        unattributed: z.ZodBoolean;
+    }, z.core.$strict>>;
+    everythingElse: z.ZodNullable<z.ZodObject<{
+        amountUsd: z.ZodNumber;
+        share: z.ZodNumber;
+        projectCount: z.ZodNumber;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export declare const resultCardSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"aibill.result_card">;
+    schemaVersion: z.ZodLiteral<1>;
+    currency: z.ZodLiteral<"USD">;
+    windowDays: z.ZodNumber;
+    mode: z.ZodEnum<{
+        mixed: "mixed";
+        connected: "connected";
+        "local-logs": "local-logs";
+        demo: "demo";
+    }>;
+    subscriptions: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        agentId: z.ZodNullable<z.ZodEnum<{
+            "claude-code": "claude-code";
+            codex: "codex";
+        }>>;
+        planLabel: z.ZodNullable<z.ZodString>;
+        connection: z.ZodEnum<{
+            connected: "connected";
+            local_logs: "local_logs";
+            detected_only: "detected_only";
+        }>;
+        committedUsdPerMonth: z.ZodNullable<z.ZodNumber>;
+        apiEquivalentUsd: z.ZodNullable<z.ZodNumber>;
+        providerBilledUsd: z.ZodNullable<z.ZodNumber>;
+        detectedUnverifiedUsd: z.ZodNullable<z.ZodNumber>;
+        runways: z.ZodArray<z.ZodObject<{
+            kind: z.ZodEnum<{
+                "five-hour": "five-hour";
+                weekly: "weekly";
+            }>;
+            remainingPercent: z.ZodNumber;
+            resetsAt: z.ZodString;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+    totals: z.ZodObject<{
+        subscriptionCommitted: z.ZodObject<{
+            amountUsd: z.ZodNullable<z.ZodNumber>;
+            pricedSubs: z.ZodNumber;
+            totalSubs: z.ZodNumber;
+        }, z.core.$strict>;
+        apiEquivalent: z.ZodObject<{
+            amountUsd: z.ZodNullable<z.ZodNumber>;
+            financialEvidence: z.ZodEnum<{
+                estimated: "estimated";
+                missing: "missing";
+            }>;
+        }, z.core.$strict>;
+        providerBilled: z.ZodObject<{
+            amountUsd: z.ZodNullable<z.ZodNumber>;
+            financialEvidence: z.ZodEnum<{
+                verified: "verified";
+                missing: "missing";
+            }>;
+        }, z.core.$strict>;
+        blended: z.ZodNull;
+        blendPolicy: z.ZodLiteral<"never_blended">;
+    }, z.core.$strict>;
+    byProject: z.ZodNullable<z.ZodObject<{
+        basis: z.ZodEnum<{
+            provider_billed: "provider_billed";
+            api_equivalent: "api_equivalent";
+        }>;
+        rows: z.ZodArray<z.ZodObject<{
+            project: z.ZodString;
+            amountUsd: z.ZodNumber;
+            share: z.ZodNumber;
+            unattributed: z.ZodBoolean;
+        }, z.core.$strict>>;
+        everythingElse: z.ZodNullable<z.ZodObject<{
+            amountUsd: z.ZodNumber;
+            share: z.ZodNumber;
+            projectCount: z.ZodNumber;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type ResultCardBuildInput = {
+    mode: ResultCardMode;
+    /** Evidence window in days (metadata; records must already be window-scoped). */
+    windowDays?: number;
+    records: readonly UsageRecord[];
+    detectedPlans?: readonly DetectedPlan[];
+    /**
+     * Optional fresh runway evidence keyed by agent id. The builder orders each
+     * list most-urgent first and keeps at most two. Freshness filtering is the
+     * caller's responsibility (existing statusline freshness rules).
+     */
+    runways?: Readonly<Partial<Record<"claude-code" | "codex", readonly ResultCardRunway[]>>>;
+    /**
+     * Optional provider-side subscription plan facts for provider-only rows
+     * (e.g. a priced Cursor plan). Nothing detects these automatically today;
+     * absent entries render honestly as plan-not-priced.
+     */
+    providerPlans?: readonly {
+        provider: string;
+        planLabel: string | null;
+        committedUsdPerMonth: number | null;
+    }[];
+};
+export type ResultCardRecordBasis = "api_equivalent" | "provider_billed" | "detected_unverified" | "none";
+/**
+ * The one basis classifier every surface shares (§1.2): verified dollars are
+ * provider_billed; estimated dollars are api_equivalent ONLY when they were
+ * priced at published API rates; every other priced-but-unverified dollar is
+ * detected_unverified (disclosure-only). Exported so renderers can keep their
+ * bars/tables same-kind (QA finding M2) instead of re-deriving basis rules.
+ */
+export declare function classifyResultCardRecordBasis(record: UsageRecord, mode: ResultCardMode): ResultCardRecordBasis;
+/** Project names clip at 24 chars + `…` on every renderer (§1.1). */
+export declare function clipResultCardProjectName(name: string): string;
+/**
+ * Largest-remainder integer percentages: printed shares sum to exactly 100.
+ * Input weights need not be normalized.
+ */
+export declare function largestRemainderPercents(weights: readonly number[]): number[];
+/**
+ * Build the canonical result card from window-scoped usage records plus
+ * locally detected plans. Pure and deterministic; every §1.1 rule lives here,
+ * not in the renderers.
+ */
+export declare function buildResultCard(input: ResultCardBuildInput): ResultCard;
+export type ResultCardProjectLineInput = {
+    card: ResultCard;
+    /** The same window-scoped records the card was built from. */
+    records: readonly UsageRecord[];
+    /** Current project id (working-folder basename); undefined = unattributed cwd. */
+    currentProjectId: string | undefined;
+};
+/**
+ * The improve card's PROJECT line (§3): the CURRENT project's standing on the
+ * card's primary basis — one line, N=1 plus context. Returns undefined when
+ * no project attribution exists for the current directory (the line is
+ * omitted, never fabricated). Rank counts named projects; the unattributed
+ * bucket is excluded from ranking but included in the denominator total.
+ */
+export declare function buildResultCardProjectLine(input: ResultCardProjectLineInput): string | undefined;
+/** `committed $320/mo` amount part: "$320/mo" (whole dollars, list prices). */
+export declare function formatCommittedPerMonth(amountUsd: number): string;
+/**
+ * API-equivalent figures always carry `~` and round to whole dollars.
+ * Real-but-tiny usage prints `~<$1` (QA MINOR-4): `~$0` reads as absence.
+ */
+export declare function formatApproxUsd(amountUsd: number): string;
+/** Provider-billed money is never compacted, rounded, or approximated. */
+export declare function formatBilledUsdExact(amountUsd: number): string;
+//# sourceMappingURL=resultCard.d.ts.map