@trazum/core 2.3.0 → 2.4.0

package/dist/anthropic-cost.d.ts

@@ -0,0 +1,173 @@
+/**
+ * What the provider billed, beside what Trazum computed.
+ *
+ * The one figure nobody else gives you. Every other door here answers *what
+ * did this usage cost at these rates*; the provider answers *what did we
+ * charge you*, and the two are different questions that produce different
+ * numbers. The gap between them is the interesting part, and until this file
+ * there was nowhere to look at it.
+ *
+ * ## Why the two are never added
+ *
+ * `docs/commands.md` already states the rule for LiteLLM's `total_cost`: a
+ * provider-billed figure is printed **beside** Trazum's and never merged into
+ * it, because two price tables summed into one number is how a report becomes
+ * quietly wrong. This file is that rule with arithmetic attached. Nothing here
+ * corrects one figure with the other, and nothing here decides which is right:
+ * they are two measurements of the same window, and the reader is the one
+ * entitled to say which they trust.
+ *
+ * ## The unit, which is the trap
+ *
+ * `amount` is **a decimal string in the currency's lowest unit**: `"123.45"`
+ * in USD is $1.2345, not $123.45. A reader of this API who takes the field for
+ * dollars overstates a bill by a hundred times, and the figure looks entirely
+ * plausible on a large organisation. It is divided by a hundred here, once, at
+ * the end, and a test asserts the factor against the schema's own example.
+ *
+ * `currency` is documented as always `USD` today. It is still checked: a
+ * converter that assumed it would be silently wrong the day it changes, and
+ * summing two currencies into one total is the same failure as summing two
+ * price tables. Anything but USD is refused rather than converted, because a
+ * conversion needs a rate and inventing one is the sin this product is built
+ * against.
+ *
+ * ## What the decomposition is for
+ *
+ * A difference nobody can attribute is a number that starts an argument. This
+ * report can attribute most of one, when it is fetched with
+ * `group_by[]=description`:
+ *
+ * - **`cost_type` other than `tokens`** — web search, code execution, session
+ *   usage. Trazum prices tokens and nothing else, so every cent of these is
+ *   billed money it never claimed to cover. Named rather than blamed.
+ * - **`service_tier: "batch"`** — billed at a discount `from-anthropic`
+ *   deliberately leaves out rather than misprice at a catalogue rate.
+ *
+ * What is left after both is the **remainder**, and it is the only figure here
+ * worth arguing about: the same standard-tier tokens, priced two ways, or
+ * usage the log never saw. A tool that folded the remainder into one of the
+ * explanations would be hiding the only thing it was built to show.
+ *
+ * Without `group_by[]=description` none of that decomposition exists —
+ * `cost_type`, `service_tier` and `model` are all `null` — and the reading
+ * says so rather than reporting a remainder that is really the whole
+ * difference wearing a smaller name.
+ */
+/**
+ * What a provider charged, in the terms `reconcile` needs and no more.
+ *
+ * Two providers' reports read into it, and the difference between them is
+ * confined to the files that read them: what the money was for, whether
+ * batch can be told apart, which window, which currency.
+ */
+export interface BilledReading {
+    /** Everything billed in the window, in dollars. */
+    usd: number;
+    /** Billed for something no token rate covers: web search, code execution. */
+    notTokensUsd: number;
+    /** Billed at the batch tier, which a catalogue rate is not the rate for. */
+    batchUsd: number;
+    /**
+     * Whether this report can name a batch charge at all.
+     *
+     * Anthropic's can, once grouped by description. OpenAI's never does, so a
+     * batch discount there sits inside the remainder and the reader is told.
+     */
+    batchSeparable: boolean;
+    /**
+     * Whether the report was fetched with the grouping that names each row.
+     *
+     * Without it nothing on a row says what the money was for, so neither
+     * figure above can be separated from the total and a reconciliation can
+     * only report a difference it cannot attribute.
+     */
+    described: boolean;
+    /** The window the buckets actually cover, or `null` when there are none. */
+    window: {
+        fromMs: number;
+        toMs: number;
+    } | null;
+    /** Currencies seen that were not USD. Summing across them is refused. */
+    otherCurrencies: string[];
+}
+/** What Anthropic charged, read from its own report. */
+export interface AnthropicCostReading extends BilledReading {
+    buckets: number;
+    rows: number;
+    /** Rows whose `amount` was not a number. Counted, never read as zero. */
+    unreadableAmount: number;
+    /** `has_more`: one page of several, so the billed figure is understated. */
+    truncated: boolean;
+    /** The input was not the JSON this endpoint returns. */
+    unparseable: boolean;
+}
+/** Two measurements of one window, and what separates them. */
+export interface Reconciliation {
+    computedUsd: number;
+    billedUsd: number;
+    /** Billed minus computed. Positive means the provider charged more. */
+    differenceUsd: number;
+    /** The part of the difference the report itself accounts for. */
+    notTokensUsd: number;
+    batchUsd: number;
+    /**
+     * What neither figure explains: the same standard-tier tokens priced two
+     * ways, or usage the log never saw. The only number here worth arguing
+     * about, and never folded into the two above.
+     */
+    remainderUsd: number;
+    /** `false` when the report was not grouped in a way that names its rows. */
+    attributable: boolean;
+    /** `false` when this provider's report cannot name a batch charge at all. */
+    batchSeparable: boolean;
+    /** Why the two are not comparable, when they are not. */
+    refusal: {
+        reason: 'no-billed-window';
+    } | {
+        reason: 'window-not-covered';
+        computed: {
+            fromMs: number;
+            toMs: number;
+        };
+        billed: {
+            fromMs: number;
+            toMs: number;
+        };
+    } | {
+        reason: 'other-currency';
+        currencies: string[];
+    } | null;
+}
+/**
+ * Read a cost report. Pure, like every measuring function here, and for the
+ * same reason `anthropic-usage.ts` gives: the credential that fetches this is
+ * an admin credential, and this project holds none.
+ */
+export declare function anthropicCostReport(text: string): AnthropicCostReading;
+/**
+ * Set what Trazum computed beside what the provider billed.
+ *
+ * @param computed what Trazum priced, and the window it priced.
+ *
+ * **The windows must line up or this refuses.** A receipt for September set
+ * against a bill for August is a wrong number under a right title, which is
+ * the failure this whole product is arranged against. The billed window has
+ * to contain the computed one — daily buckets are wider than a receipt's span
+ * by construction, so containment rather than equality is the honest test —
+ * and a report that starts after the first call it is being compared with is
+ * missing money nobody would see was missing.
+ */
+export declare function reconcile(computed: {
+    usd: number;
+    fromMs: number;
+    toMs: number;
+}, billed: BilledReading): Reconciliation;
+/**
+ * Whether this text is a cost report rather than some other JSON.
+ *
+ * `amount` with `currency` beside it, in a document with buckets: the usage
+ * report has neither, and a Messages response has no buckets.
+ */
+export declare function looksLikeAnthropicCost(text: string, prefixBytes?: number): boolean;
+//# sourceMappingURL=anthropic-cost.d.ts.map

package/dist/anthropic-cost.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"anthropic-cost.d.ts","sourceRoot":"","sources":["../src/anthropic-cost.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AAEH;;;;;;GAMG;AACH,MAAM,WAAW,aAAa;IAC5B,mDAAmD;IACnD,GAAG,EAAE,MAAM,CAAC;IACZ,6EAA6E;IAC7E,YAAY,EAAE,MAAM,CAAC;IACrB,4EAA4E;IAC5E,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;;OAKG;IACH,cAAc,EAAE,OAAO,CAAC;IACxB;;;;;;OAMG;IACH,SAAS,EAAE,OAAO,CAAC;IACnB,4EAA4E;IAC5E,MAAM,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IAChD,yEAAyE;IACzE,eAAe,EAAE,MAAM,EAAE,CAAC;CAC3B;AAED,wDAAwD;AACxD,MAAM,WAAW,oBAAqB,SAAQ,aAAa;IACzD,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,yEAAyE;IACzE,gBAAgB,EAAE,MAAM,CAAC;IACzB,4EAA4E;IAC5E,SAAS,EAAE,OAAO,CAAC;IACnB,wDAAwD;IACxD,WAAW,EAAE,OAAO,CAAC;CACtB;AAED,+DAA+D;AAC/D,MAAM,WAAW,cAAc;IAC7B,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,uEAAuE;IACvE,aAAa,EAAE,MAAM,CAAC;IACtB,iEAAiE;IACjE,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,YAAY,EAAE,MAAM,CAAC;IACrB,4EAA4E;IAC5E,YAAY,EAAE,OAAO,CAAC;IACtB,6EAA6E;IAC7E,cAAc,EAAE,OAAO,CAAC;IACxB,yDAAyD;IACzD,OAAO,EACH;QAAE,MAAM,EAAE,kBAAkB,CAAA;KAAE,GAC9B;QAAE,MAAM,EAAE,oBAAoB,CAAC;QAAC,QAAQ,EAAE;YAAE,MAAM,EAAE,MAAM,CAAC;YAAC,IAAI,EAAE,MAAM,CAAA;SAAE,CAAC;QAAC,MAAM,EAAE;YAAE,MAAM,EAAE,MAAM,CAAC;YAAC,IAAI,EAAE,MAAM,CAAA;SAAE,CAAA;KAAE,GACtH;QAAE,MAAM,EAAE,gBAAgB,CAAC;QAAC,UAAU,EAAE,MAAM,EAAE,CAAA;KAAE,GAClD,IAAI,CAAC;CACV;AAOD;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,oBAAoB,CA4FtE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,SAAS,CACvB,QAAQ,EAAE;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,EACvD,MAAM,EAAE,aAAa,GACpB,cAAc,CAuChB;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,SAAO,GAAG,OAAO,CAIhF"}

package/dist/anthropic-cost.js

@@ -0,0 +1,222 @@
+/**
+ * What the provider billed, beside what Trazum computed.
+ *
+ * The one figure nobody else gives you. Every other door here answers *what
+ * did this usage cost at these rates*; the provider answers *what did we
+ * charge you*, and the two are different questions that produce different
+ * numbers. The gap between them is the interesting part, and until this file
+ * there was nowhere to look at it.
+ *
+ * ## Why the two are never added
+ *
+ * `docs/commands.md` already states the rule for LiteLLM's `total_cost`: a
+ * provider-billed figure is printed **beside** Trazum's and never merged into
+ * it, because two price tables summed into one number is how a report becomes
+ * quietly wrong. This file is that rule with arithmetic attached. Nothing here
+ * corrects one figure with the other, and nothing here decides which is right:
+ * they are two measurements of the same window, and the reader is the one
+ * entitled to say which they trust.
+ *
+ * ## The unit, which is the trap
+ *
+ * `amount` is **a decimal string in the currency's lowest unit**: `"123.45"`
+ * in USD is $1.2345, not $123.45. A reader of this API who takes the field for
+ * dollars overstates a bill by a hundred times, and the figure looks entirely
+ * plausible on a large organisation. It is divided by a hundred here, once, at
+ * the end, and a test asserts the factor against the schema's own example.
+ *
+ * `currency` is documented as always `USD` today. It is still checked: a
+ * converter that assumed it would be silently wrong the day it changes, and
+ * summing two currencies into one total is the same failure as summing two
+ * price tables. Anything but USD is refused rather than converted, because a
+ * conversion needs a rate and inventing one is the sin this product is built
+ * against.
+ *
+ * ## What the decomposition is for
+ *
+ * A difference nobody can attribute is a number that starts an argument. This
+ * report can attribute most of one, when it is fetched with
+ * `group_by[]=description`:
+ *
+ * - **`cost_type` other than `tokens`** — web search, code execution, session
+ *   usage. Trazum prices tokens and nothing else, so every cent of these is
+ *   billed money it never claimed to cover. Named rather than blamed.
+ * - **`service_tier: "batch"`** — billed at a discount `from-anthropic`
+ *   deliberately leaves out rather than misprice at a catalogue rate.
+ *
+ * What is left after both is the **remainder**, and it is the only figure here
+ * worth arguing about: the same standard-tier tokens, priced two ways, or
+ * usage the log never saw. A tool that folded the remainder into one of the
+ * explanations would be hiding the only thing it was built to show.
+ *
+ * Without `group_by[]=description` none of that decomposition exists —
+ * `cost_type`, `service_tier` and `model` are all `null` — and the reading
+ * says so rather than reporting a remainder that is really the whole
+ * difference wearing a smaller name.
+ */
+const asObject = (value) => typeof value === 'object' && value !== null && !Array.isArray(value)
+    ? value
+    : null;
+/**
+ * Read a cost report. Pure, like every measuring function here, and for the
+ * same reason `anthropic-usage.ts` gives: the credential that fetches this is
+ * an admin credential, and this project holds none.
+ */
+export function anthropicCostReport(text) {
+    const empty = {
+        usd: 0,
+        notTokensUsd: 0,
+        batchUsd: 0,
+        batchSeparable: false,
+        described: false,
+        window: null,
+        buckets: 0,
+        rows: 0,
+        otherCurrencies: [],
+        unreadableAmount: 0,
+        truncated: false,
+        unparseable: false,
+    };
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return { ...empty, unparseable: true };
+    }
+    const report = asObject(parsed);
+    if (report === null || !Array.isArray(report.data))
+        return { ...empty, unparseable: true };
+    /* Summed in cents and divided once, because summing a hundredth of a cent a
+       thousand times and dividing each time is a different number. */
+    let cents = 0;
+    let notTokensCents = 0;
+    let batchCents = 0;
+    let described = false;
+    let buckets = 0;
+    let rows = 0;
+    let unreadableAmount = 0;
+    let fromMs = null;
+    let toMs = null;
+    const otherCurrencies = new Set();
+    for (const entry of report.data) {
+        const bucket = asObject(entry);
+        if (bucket === null || typeof bucket.starting_at !== 'string')
+            continue;
+        buckets += 1;
+        const from = Date.parse(bucket.starting_at);
+        const to = typeof bucket.ending_at === 'string' ? Date.parse(bucket.ending_at) : Number.NaN;
+        if (Number.isFinite(from))
+            fromMs = fromMs === null ? from : Math.min(fromMs, from);
+        if (Number.isFinite(to))
+            toMs = toMs === null ? to : Math.max(toMs, to);
+        if (!Array.isArray(bucket.results))
+            continue;
+        for (const found of bucket.results) {
+            const result = asObject(found);
+            if (result === null)
+                continue;
+            rows += 1;
+            /* A currency this cannot sum stops it being summed at all, rather than
+               being quietly added to a dollar total. */
+            if (typeof result.currency === 'string' && result.currency !== 'USD') {
+                otherCurrencies.add(result.currency);
+            }
+            const amount = typeof result.amount === 'string' ? Number(result.amount) : Number.NaN;
+            if (!Number.isFinite(amount)) {
+                unreadableAmount += 1;
+                continue;
+            }
+            cents += amount;
+            if (typeof result.cost_type === 'string') {
+                described = true;
+                if (result.cost_type !== 'tokens')
+                    notTokensCents += amount;
+            }
+            if (typeof result.service_tier === 'string') {
+                described = true;
+                if (result.service_tier === 'batch')
+                    batchCents += amount;
+            }
+        }
+    }
+    return {
+        usd: cents / 100,
+        notTokensUsd: notTokensCents / 100,
+        batchUsd: batchCents / 100,
+        batchSeparable: described,
+        described,
+        window: fromMs === null || toMs === null ? null : { fromMs, toMs },
+        buckets,
+        rows,
+        otherCurrencies: [...otherCurrencies],
+        unreadableAmount,
+        truncated: report.has_more === true,
+        unparseable: false,
+    };
+}
+/**
+ * Set what Trazum computed beside what the provider billed.
+ *
+ * @param computed what Trazum priced, and the window it priced.
+ *
+ * **The windows must line up or this refuses.** A receipt for September set
+ * against a bill for August is a wrong number under a right title, which is
+ * the failure this whole product is arranged against. The billed window has
+ * to contain the computed one — daily buckets are wider than a receipt's span
+ * by construction, so containment rather than equality is the honest test —
+ * and a report that starts after the first call it is being compared with is
+ * missing money nobody would see was missing.
+ */
+export function reconcile(computed, billed) {
+    const bare = {
+        computedUsd: computed.usd,
+        billedUsd: billed.usd,
+        differenceUsd: billed.usd - computed.usd,
+        notTokensUsd: billed.notTokensUsd,
+        batchUsd: billed.batchUsd,
+        remainderUsd: 0,
+        attributable: billed.described,
+        batchSeparable: billed.batchSeparable,
+    };
+    if (billed.otherCurrencies.length > 0) {
+        return { ...bare, refusal: { reason: 'other-currency', currencies: billed.otherCurrencies } };
+    }
+    if (billed.window === null)
+        return { ...bare, refusal: { reason: 'no-billed-window' } };
+    if (billed.window.fromMs > computed.fromMs || billed.window.toMs < computed.toMs) {
+        return {
+            ...bare,
+            refusal: {
+                reason: 'window-not-covered',
+                computed: { fromMs: computed.fromMs, toMs: computed.toMs },
+                billed: billed.window,
+            },
+        };
+    }
+    /*
+      The remainder is what is left when the report's own explanations are taken
+      out of the difference, and it is deliberately not clamped at zero. A
+      negative one is a real answer -- Trazum priced more than the provider
+      charged -- and reporting it as zero would hide a stale rate in exactly the
+      direction that costs somebody money.
+    */
+    return {
+        ...bare,
+        remainderUsd: bare.differenceUsd - billed.notTokensUsd - billed.batchUsd,
+        refusal: null,
+    };
+}
+/**
+ * Whether this text is a cost report rather than some other JSON.
+ *
+ * `amount` with `currency` beside it, in a document with buckets: the usage
+ * report has neither, and a Messages response has no buckets.
+ */
+export function looksLikeAnthropicCost(text, prefixBytes = 8192) {
+    const head = text.slice(0, prefixBytes);
+    if (!head.includes('"amount"') || !head.includes('"currency"'))
+        return false;
+    return head.includes('"starting_at"') || head.includes('"has_more"');
+}
+//# sourceMappingURL=anthropic-cost.js.map

package/dist/anthropic-cost.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"anthropic-cost.js","sourceRoot":"","sources":["../src/anthropic-cost.ts"],"names":[],"mappings":"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"}

package/dist/anthropic-usage.d.ts

@@ -0,0 +1,192 @@
+/**
+ * Anthropic's own usage report, read as a usage log.
+ *
+ * The fifth converter in the pattern `from-claude-code` started, and the first
+ * one that reads a **provider** rather than a tool sitting in front of one.
+ * Every other converter answers *what did the calls my proxy saw cost*; this
+ * one answers *what does the provider say my organisation used*, which is the
+ * question a finance team asks and the one no local log can answer, because a
+ * log only knows the machines it was written on.
+ *
+ * ## Why this takes a file and not a key
+ *
+ * The Usage & Cost API needs an **admin** credential: an `sk-ant-admin01-…`
+ * key, an `org:admin` OAuth token, or an unscoped personal or service account
+ * key. Workspace keys do not work. That credential can read every workspace's
+ * usage and manage the organisation's members and keys, which makes it exactly
+ * the kind of secret this project has spent its whole design not holding.
+ *
+ * So this function takes the **response**, not the credential. The operator
+ * runs one `curl` with their own key, in their own shell, and pipes the JSON
+ * here. Trazum never sees the key, never makes the request, and stays a pure
+ * function of text — which is also why this file can be tested without a
+ * network and why the deterministic core is still deterministic.
+ *
+ * ## The format is derived, not guessed
+ *
+ * Every field below is from the published response schema of
+ * `GET /v1/organizations/usage_report/messages`: `data[]` of time buckets with
+ * `starting_at`, `ending_at` and `results[]`, and each result carrying
+ * `uncached_input_tokens`, `cache_read_input_tokens`, `cache_creation`
+ * (`ephemeral_5m_input_tokens`, `ephemeral_1h_input_tokens`), `output_tokens`,
+ * `model`, `service_tier` and `server_tool_use.web_search_requests`.
+ *
+ * The cache shape needs no translation at all: `parseUsageLine` already reads
+ * `cache_creation.ephemeral_5m_input_tokens` and its 1-hour sibling, because
+ * that is the shape the Messages API itself returns. The one rename is
+ * `uncached_input_tokens` to `input_tokens`, and it is a rename rather than a
+ * sum: this report reports cached reads **beside** the uncached input rather
+ * than folded into it, which is the Anthropic shape and not the OpenAI one.
+ *
+ * ## What it refuses to price, and counts instead
+ *
+ * **A result with no model.** `model` is `null` unless the caller passed
+ * `group_by[]=model`. Nothing on a row without it says what answered, so
+ * nothing can price it. Refused, counted, and the count names the missing
+ * parameter — a converter that quietly returned an empty log would send
+ * somebody looking for a bug in their key.
+ *
+ * **A non-standard service tier.** Batch is billed at a discount and priority
+ * is not billed like either; a catalogue rate is the standard rate. Pricing a
+ * batch row from it would overstate a bill by half and look right doing it,
+ * which is this product's one unforgivable failure. Those rows are left out
+ * and counted, the same way an unpriceable line becomes a named gap rather
+ * than a guess.
+ *
+ * **Web search requests.** `server_tool_use.web_search_requests` is billed per
+ * request, not per token, so no token rate reaches it. Counted and named, so a
+ * total that is missing them says so.
+ *
+ * **A truncated report.** `has_more: true` means the answer is one page of
+ * several, and a bill built from one page is understated by however many pages
+ * were not asked for. Said out loud rather than left for somebody to notice in
+ * a figure.
+ *
+ * ## What deliberately does not cross
+ *
+ * `account_id`, `service_account_id` and `api_key_id` are read by nothing
+ * here. The first two name people; the third names a credential. None of them
+ * is a project name and none of them reaches the output.
+ *
+ * `workspace_id` is read only when the operator hands over a mapping, because
+ * a workspace id is not a project name and turning one into the other is a
+ * decision rather than an inference. `labelByWorkspace` is that decision,
+ * written down: the same shape `--label-by-cwd` established for transcripts,
+ * exact rather than prefixed, because an opaque identifier has no hierarchy
+ * to take the longest match of.
+ *
+ * ## The `null` that means two things, and how it is told apart
+ *
+ * The report's own schema says `workspace_id` is `null` **both** when the
+ * caller did not group by workspace **and** for the default workspace. One
+ * value, two meanings, and a mapping that guessed between them would put the
+ * default workspace's money on a label nobody chose or leave it off one they
+ * did.
+ *
+ * It is derived instead: if any result in the report carries a workspace id,
+ * the report was grouped, and a `null` there is the default workspace — so a
+ * rule written for `null` applies to it. If no result carries one, nothing
+ * distinguishes the two readings, `null` rules do not apply, and the
+ * conversion says the split was asked for and could not be made.
+ *
+ * ## The instant, and why it is the bucket's
+ *
+ * This report has no calls in it. A bucket is an interval and its usage is a
+ * sum over that interval, so every record made from it carries the bucket's
+ * `starting_at` — a day's usage at that day's start, an hour's at the hour's.
+ * Anything finer would be a precision the source does not have, and
+ * `bucket_width=1h` is there for an operator who wants it.
+ */
+/**
+ * One workspace, and the project name the operator gives it.
+ *
+ * Matched exactly, never by prefix: a workspace id is opaque and two of them
+ * sharing leading characters share nothing at all. `null` names the default
+ * workspace, which is the only workspace the report identifies by absence.
+ */
+export interface WorkspaceLabel {
+    workspace: string | null;
+    label: string;
+}
+/** One converted record, shaped exactly as `parseUsageLine` reads it. */
+export interface AnthropicUsageRecord {
+    model: string;
+    ts: string;
+    label?: string;
+    usage: {
+        input_tokens: number;
+        output_tokens: number;
+        cache_read_input_tokens?: number;
+        cache_creation?: {
+            ephemeral_5m_input_tokens: number;
+            ephemeral_1h_input_tokens: number;
+        };
+    };
+}
+export interface AnthropicUsageConversion {
+    records: AnthropicUsageRecord[];
+    /** Time buckets in the report, including intervals with no usage. */
+    buckets: number;
+    /** Results that became records. */
+    rows: number;
+    /** Results with `model: null`, which nothing can price. */
+    unnamedModel: number;
+    /** Results at a tier a standard rate would misprice. */
+    nonStandardTier: number;
+    /**
+     * Whether any result named its tier at all.
+     *
+     * `false` means the report was not grouped by `service_tier`, so a batch row
+     * and a standard row are indistinguishable here and the discount, if any,
+     * is invisible. Not an error and not a refusal: most organisations run
+     * standard only. It is said because the alternative is a reader assuming a
+     * question was answered that was never asked.
+     */
+    tierNamed: boolean;
+    /** Server-side tool calls billed per request, which no token rate prices. */
+    webSearchRequests: number;
+    /** `has_more`: this is one page and the bill from it is understated. */
+    truncated: boolean;
+    /** Records whose label came from a workspace rule rather than `--label`. */
+    labelledByWorkspace: number;
+    /**
+     * Results carrying a workspace no rule named.
+     *
+     * They keep `--label` if there is one and go unattributed if there is not,
+     * which is the same fallback `--label-by-cwd` makes: a workspace nobody
+     * wrote a rule for is unattributed rather than attributed to a neighbour.
+     */
+    unruledWorkspace: number;
+    /**
+     * Rules were given and no result carried a workspace id.
+     *
+     * Either the report was not grouped by workspace or this organisation uses
+     * only the default one, and nothing here can tell those apart. The split
+     * asked for was not made, and that is said rather than left to be noticed.
+     */
+    workspaceNotGrouped: boolean;
+    /** The input was not the JSON this endpoint returns. */
+    unparseable: number;
+}
+/**
+ * @param label the project this usage belongs to, chosen by the operator.
+ *
+ * Optional, and absent means the records carry none — the unattributed bucket
+ * every other door already understands. The provider does not know this
+ * organisation's project names and neither does this file.
+ */
+export declare function anthropicUsageRecords(text: string, options?: {
+    label?: string;
+    labelByWorkspace?: readonly WorkspaceLabel[];
+}): AnthropicUsageConversion;
+/**
+ * Whether this text is an Anthropic usage report rather than some other JSON.
+ *
+ * Three fields together, because each alone is too common to decide on:
+ * `uncached_input_tokens` is this endpoint's own name for a count every other
+ * shape calls something else, and a report always carries buckets with a
+ * `starting_at`. A sniffer that matched on `output_tokens` alone would claim
+ * every Messages response ever saved to a file.
+ */
+export declare function looksLikeAnthropicUsage(text: string, prefixBytes?: number): boolean;
+//# sourceMappingURL=anthropic-usage.d.ts.map

package/dist/anthropic-usage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"anthropic-usage.d.ts","sourceRoot":"","sources":["../src/anthropic-usage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkGG;AAEH;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,yEAAyE;AACzE,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,EAAE;QACL,YAAY,EAAE,MAAM,CAAC;QACrB,aAAa,EAAE,MAAM,CAAC;QACtB,uBAAuB,CAAC,EAAE,MAAM,CAAC;QACjC,cAAc,CAAC,EAAE;YACf,yBAAyB,EAAE,MAAM,CAAC;YAClC,yBAAyB,EAAE,MAAM,CAAC;SACnC,CAAC;KACH,CAAC;CACH;AAED,MAAM,WAAW,wBAAwB;IACvC,OAAO,EAAE,oBAAoB,EAAE,CAAC;IAChC,qEAAqE;IACrE,OAAO,EAAE,MAAM,CAAC;IAChB,mCAAmC;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,2DAA2D;IAC3D,YAAY,EAAE,MAAM,CAAC;IACrB,wDAAwD;IACxD,eAAe,EAAE,MAAM,CAAC;IACxB;;;;;;;;OAQG;IACH,SAAS,EAAE,OAAO,CAAC;IACnB,6EAA6E;IAC7E,iBAAiB,EAAE,MAAM,CAAC;IAC1B,wEAAwE;IACxE,SAAS,EAAE,OAAO,CAAC;IACnB,4EAA4E;IAC5E,mBAAmB,EAAE,MAAM,CAAC;IAC5B;;;;;;OAMG;IACH,gBAAgB,EAAE,MAAM,CAAC;IACzB;;;;;;OAMG;IACH,mBAAmB,EAAE,OAAO,CAAC;IAC7B,wDAAwD;IACxD,WAAW,EAAE,MAAM,CAAC;CACrB;AAKD;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,gBAAgB,CAAC,EAAE,SAAS,cAAc,EAAE,CAAA;CAAO,GAC7E,wBAAwB,CAgK1B;AAED;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,SAAO,GAAG,OAAO,CAIjF"}