@zanii/blackbox 0.0.0-stage → 0.1.0

package/dist/money/index.d.ts

@@ -0,0 +1,114 @@
+import { type LoadedPrices } from "../cost/index.ts";
+import type { Summary } from "../fleet/index.ts";
+/** `{model: micro_usd}` over the priced calls, sorted by model. */
+export declare function modelSpend(lines: readonly string[], prices: LoadedPrices): Record<string, number>;
+export interface Statement {
+    lines: Array<{
+        model: string;
+        micro_usd: number;
+    }>;
+}
+/** Why a statement is invalid, or undefined. */
+export declare function checkStatement(s: unknown): string | undefined;
+export declare function reconcileBilling(ours: Record<string, number>, statement: Statement, tolerancePpm?: number): {
+    v: 1;
+    tolerance_ppm: number;
+    ours_micro_usd: number;
+    theirs_micro_usd: number;
+    diff_micro_usd: number;
+    ok: boolean;
+    models: {
+        model: string;
+        ours: number;
+        theirs: number;
+        diff: number;
+        status: string;
+    }[];
+};
+export interface Baseline {
+    label: string;
+    successes: number;
+    median_spend_micro_usd: number;
+    p90_spend_micro_usd: number;
+    median_model_calls: number;
+    median_tool_calls: number;
+}
+/** Per label, over successful sessions only (spec/money.md §3). */
+export declare function baselines(summaries: readonly Summary[]): {
+    labels: Baseline[];
+};
+/** Will the remaining budget reach the destination? (spec/money.md §4) */
+export declare function fuel(summary: Summary, budgetMicroUsd: number | null, baseline: Baseline | null): {
+    spent_micro_usd: number;
+    budget_micro_usd: number | null;
+    expected_total_micro_usd: number | null;
+    p90_total_micro_usd: number | null;
+    verdict: string;
+};
+export type AmountUnit = "usd" | "cents" | "micro_usd" | "aed";
+/** spec/money.md §2a-b: an exact decimal amount (string, or a JSON number's text) to integer
+ * micro-USD, rounded half up. `unit` is what the amount counts. */
+export declare function decimalToMicroUsd(value: unknown, unit: AmountUnit): number;
+/** spec/money.md §2a: Anthropic's cost report pages (grouped by description) as a statement. */
+export declare function anthropicStatement(pages: readonly unknown[]): Statement;
+/** spec/money.md §2a: OpenAI's organization costs pages (grouped by line_item) as a statement. */
+export declare function openaiStatement(pages: readonly unknown[]): Statement;
+/** spec/money.md §2b: every value at a path (`a.b[].c`, `[]` alone for a list itself). */
+export declare function resolvePath(value: unknown, path: string): unknown[];
+/** spec/money.md §2b: a CSV export with named columns as a statement. */
+export declare function csvStatement(text: string, opts: {
+    model_column: string;
+    amount_column: string;
+    unit: AmountUnit;
+    delimiter?: string;
+}): Statement;
+export interface Connector {
+    v: 1;
+    name: string;
+    request: {
+        url: string;
+        headers?: Record<string, string>;
+        method?: "GET" | "POST";
+        body?: string;
+        content_type?: string;
+    };
+    results: string;
+    model: string;
+    amount: string;
+    unit: AmountUnit;
+    currency?: {
+        path: string;
+        equals: string;
+    };
+    /** spec/money.md §2b: how responses are read; json by default. */
+    format?: "json" | "xml";
+    next?: {
+        cursor: string;
+        param: string;
+    } | {
+        page_param: string;
+        first_page?: number;
+        size_param?: string;
+        size?: number;
+    } | {
+        offset_param: string;
+        size: number;
+        size_param?: string;
+    };
+}
+/** spec/money.md §2b: why a connector file is invalid, or undefined. */
+export declare function checkConnector(value: unknown): string | undefined;
+/** spec/money.md §2b: pages from a connector's API as a statement. */
+export declare function customStatement(pages: readonly unknown[], connector: Connector): Statement;
+/** spec/money.md §2b: the query parameters for the next request, or null when there are no more. */
+export declare function pageParams(c: Connector, pages: readonly unknown[]): Array<[string, string]> | null;
+/** spec/money.md §2b: XML as `{root: [value]}`. No DTDs, so no external or expanding entities. */
+export declare function parseXml(text: string): Record<string, unknown>;
+/** spec/money.md §2b: the next request a connector makes, or null when there are no more. */
+export declare function requestFor(c: Connector, pages: readonly unknown[], from: string, to: string): {
+    method: "GET" | "POST";
+    url: string;
+    query: Array<[string, string]>;
+    body?: string;
+    content_type?: string;
+} | null;