@trazum/core 1.81.0 → 1.83.0

package/dist/litellm.js

@@ -0,0 +1,207 @@
+/**
+ * LiteLLM's spend log, read as a usage log.
+ *
+ * `from-claude-code` proved the pattern and `from-otel` generalised it: a pure
+ * converter turns one tool's export into Trazum's usage-log records, and every
+ * door prices it from there. LiteLLM is the gateway a great many teams already
+ * put in front of every provider, so its `LiteLLM_SpendLogs` table is the one
+ * export most likely to already exist on somebody's disk.
+ *
+ * **The format is derived, not guessed.** Every field below is read off
+ * `litellm/proxy/schema.prisma` in BerriAI/litellm, model `LiteLLM_SpendLogs`.
+ * A converter written from memory of an API is a converter that silently
+ * mis-reads somebody's bill, and this project has one rule above all others
+ * about numbers it cannot justify.
+ *
+ * ## What maps
+ *
+ * | LiteLLM | Trazum |
+ * | --- | --- |
+ * | `model` | `model` |
+ * | `prompt_tokens` | `usage.input_tokens` |
+ * | `completion_tokens` | `usage.output_tokens` |
+ * | `startTime` | `ts` |
+ * | `session_id` | `session` |
+ * | `request_tags[0]`, else `metadata.tags[0]`, else `model_group` | `label` |
+ *
+ * ## What deliberately does not cross
+ *
+ * The row carries `messages` and `response` — the prompt itself and the
+ * completion — plus `api_key` (hashed, still credential-shaped),
+ * `requester_ip_address`, `user` and `end_user`. **None of it is read.** The
+ * converter names the fields it takes and takes nothing else, and a fixture
+ * plants a marker in each of them and greps the whole output.
+ *
+ * ## What it refuses to invent
+ *
+ * `cache_hit` is a flag and `cache_key` an identifier; neither is a token
+ * count. A converted record therefore carries no cache split at all, and the
+ * caching questions come back `cannot-tell` rather than answered from a
+ * guess — the same refusal as inventing a price. `cacheFlagged` counts the
+ * rows that said "hit" so the operator can see the gap is real rather than
+ * empty.
+ *
+ * `spend` is LiteLLM's own priced figure and is **never** merged into
+ * Trazum's catalogue-priced total. It is a second measurement of the same
+ * calls, kept apart the way the store's provider-billed standing is kept
+ * apart from the log's, and returned on its own so a caller who wants to
+ * compare the two can, deliberately.
+ */
+const asObject = (value) => typeof value === 'object' && value !== null && !Array.isArray(value)
+    ? value
+    : null;
+const tryParse = (text) => {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+};
+const asCount = (value) => {
+    const n = typeof value === 'string' ? Number(value) : value;
+    return typeof n === 'number' && Number.isFinite(n) && n >= 0 ? n : undefined;
+};
+/**
+ * The first tag LiteLLM carries for a row, from the two places it puts them.
+ *
+ * `request_tags` is the documented column and `metadata.tags` is where the
+ * proxy writes them when the caller passes them in the request body. First
+ * only: a workload has one name in a bill, and joining several tags into one
+ * label would invent a workload that does not exist.
+ */
+function labelOf(row) {
+    const fromColumn = Array.isArray(row.request_tags) ? row.request_tags : null;
+    if (fromColumn !== null && typeof fromColumn[0] === 'string' && fromColumn[0] !== '') {
+        return fromColumn[0];
+    }
+    const metadata = asObject(row.metadata);
+    const fromMetadata = metadata !== null && Array.isArray(metadata.tags) ? metadata.tags : null;
+    if (fromMetadata !== null && typeof fromMetadata[0] === 'string' && fromMetadata[0] !== '') {
+        return fromMetadata[0];
+    }
+    // The public model name a proxy route is known by. A weaker label than a
+    // tag — it groups by route rather than by workload — and better than none.
+    if (typeof row.model_group === 'string' && row.model_group !== '')
+        return row.model_group;
+    return undefined;
+}
+/** `startTime` as an ISO instant, or undefined when it is not a time. */
+function timeOf(row) {
+    const raw = row.startTime ?? row.start_time;
+    if (typeof raw !== 'string' && typeof raw !== 'number')
+        return undefined;
+    const ms = typeof raw === 'number' ? raw : Date.parse(raw);
+    if (!Number.isFinite(ms))
+        return undefined;
+    return new Date(ms).toISOString();
+}
+/**
+ * Convert a LiteLLM spend-log export.
+ *
+ * Accepts a JSON array of rows, a single row, `{ data: [...] }` as the proxy's
+ * own endpoints return it, or newline-delimited rows — so a `psql --json`
+ * dump, an API response and a streamed capture all work. Pure over its input.
+ */
+export function litellmRecords(text) {
+    const out = {
+        records: [],
+        rows: 0,
+        unnamedModel: 0,
+        noTokens: 0,
+        cacheFlagged: 0,
+        reportedSpendUsd: null,
+        unparseable: 0,
+    };
+    const rows = [];
+    const whole = tryParse(text);
+    if (whole !== undefined) {
+        if (Array.isArray(whole))
+            rows.push(...whole);
+        else {
+            const doc = asObject(whole);
+            // `{ data: [...] }` is what the proxy's spend endpoints return.
+            if (doc !== null && Array.isArray(doc.data))
+                rows.push(...doc.data);
+            else if (doc !== null)
+                rows.push(doc);
+        }
+    }
+    else {
+        for (const line of text.split('\n')) {
+            if (line.trim() === '')
+                continue;
+            const parsed = tryParse(line);
+            if (parsed === undefined)
+                out.unparseable += 1;
+            else if (Array.isArray(parsed))
+                rows.push(...parsed);
+            else
+                rows.push(parsed);
+        }
+    }
+    let spend = 0;
+    let sawSpend = false;
+    for (const raw of rows) {
+        const row = asObject(raw);
+        if (row === null)
+            continue;
+        // A spend log row is one that carries at least one of the two token
+        // columns. Anything else in the same file is not a call and is skipped
+        // rather than converted into a record of zero.
+        const input = asCount(row.prompt_tokens);
+        const output = asCount(row.completion_tokens);
+        if (input === undefined && output === undefined)
+            continue;
+        out.rows += 1;
+        if (input === 0 && output === 0)
+            out.noTokens += 1;
+        if (row.cache_hit === true || row.cache_hit === 'true' || row.cache_hit === 'True') {
+            out.cacheFlagged += 1;
+        }
+        const reported = asCount(row.spend);
+        if (reported !== undefined) {
+            spend += reported;
+            sawSpend = true;
+        }
+        const model = typeof row.model === 'string' ? row.model.trim() : '';
+        if (model === '') {
+            // Counted, never guessed at. `model_group` is a route name, not a model,
+            // and pricing a call by the route it took would be a figure attributed
+            // to something it does not describe.
+            out.unnamedModel += 1;
+            continue;
+        }
+        const ts = timeOf(row);
+        const label = labelOf(row);
+        const session = typeof row.session_id === 'string' && row.session_id !== ''
+            ? row.session_id
+            : undefined;
+        out.records.push({
+            model,
+            ...(ts !== undefined ? { ts } : {}),
+            ...(label !== undefined ? { label } : {}),
+            ...(session !== undefined ? { session } : {}),
+            usage: { input_tokens: input ?? 0, output_tokens: output ?? 0 },
+        });
+    }
+    out.reportedSpendUsd = sawSpend ? spend : null;
+    return out;
+}
+/**
+ * Whether a file looks like a LiteLLM spend log, by shape.
+ *
+ * Deliberately narrow: `request_id` beside one of the two token columns, and
+ * a field no other export in this project carries. A looser test would claim
+ * an OpenAI usage response, whose rows also have `prompt_tokens`, and refuse
+ * it in this file's words instead of letting the code that can read it try.
+ */
+export function looksLikeLiteLlm(text, prefixBytes = 8192) {
+    const head = text.slice(0, prefixBytes);
+    if (!head.includes('prompt_tokens') && !head.includes('completion_tokens'))
+        return false;
+    return (head.includes('"request_id"') ||
+        head.includes('"custom_llm_provider"') ||
+        head.includes('"model_group"'));
+}
+//# sourceMappingURL=litellm.js.map

package/dist/litellm.js.map

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

package/dist/measured-profile.d.ts

@@ -68,6 +68,10 @@ export interface MeasuredUsage {
      * call is the same size. It is handed over as the better of two
      * approximations — a measured token share beats a typed call share — and
      * named honestly here so no rendering can call it something it is not.
+     *
+     * The denominator is every input token, **writes included**. Leaving writes
+     * out made a constantly-rewritten cache report a high hit rate, which is the
+     * one workload that most needs to be told otherwise.
      */
     cacheReadShare: number;
     /**

package/dist/measured-profile.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"measured-profile.d.ts","sourceRoot":"","sources":["../src/measured-profile.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAGH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AACrD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE/C;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,cAAc,IAAI,CAAC;AAEhC,iFAAiF;AACjF,eAAO,MAAM,aAAa,KAAK,CAAC;AAEhC,MAAM,WAAW,aAAa;IAC5B,6EAA6E;IAC7E,OAAO,EAAE,YAAY,CAAC;IACtB,oEAAoE;IACpE,KAAK,EAAE,MAAM,CAAC;IACd,2EAA2E;IAC3E,QAAQ,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB;;;;;OAKG;IACH,MAAM,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IACpD;;;;;;;;;OASG;IACH,cAAc,EAAE,MAAM,CAAC;IACvB;;;;OAIG;IACH,MAAM,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,kBAAkB,EAAE,MAAM,CAAA;KAAE,CAAC;IACtE,iEAAiE;IACjE,gBAAgB,EAAE,OAAO,CAAC;CAC3B;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,kBAAkB,EAC1B,KAAK,EAAE,MAAM,EACb,OAAO,GAAE;IAAE,aAAa,CAAC,EAAE,OAAO,CAAA;CAAO,GACxC,aAAa,GAAG,IAAI,CAuDtB;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,aAAa;IAC5B,yDAAyD;IACzD,MAAM,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAClE,yEAAyE;IACzE,oBAAoB,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAC9D,2EAA2E;IAC3E,oBAAoB,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CAC7D;AAED,wBAAgB,aAAa,CAC3B,MAAM,EAAE,kBAAkB,EAC1B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC7B,aAAa,CAsBf"}
+{"version":3,"file":"measured-profile.d.ts","sourceRoot":"","sources":["../src/measured-profile.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAGH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AACrD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE/C;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,cAAc,IAAI,CAAC;AAEhC,iFAAiF;AACjF,eAAO,MAAM,aAAa,KAAK,CAAC;AAEhC,MAAM,WAAW,aAAa;IAC5B,6EAA6E;IAC7E,OAAO,EAAE,YAAY,CAAC;IACtB,oEAAoE;IACpE,KAAK,EAAE,MAAM,CAAC;IACd,2EAA2E;IAC3E,QAAQ,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB;;;;;OAKG;IACH,MAAM,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IACpD;;;;;;;;;;;;;OAaG;IACH,cAAc,EAAE,MAAM,CAAC;IACvB;;;;OAIG;IACH,MAAM,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,kBAAkB,EAAE,MAAM,CAAA;KAAE,CAAC;IACtE,iEAAiE;IACjE,gBAAgB,EAAE,OAAO,CAAC;CAC3B;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,kBAAkB,EAC1B,KAAK,EAAE,MAAM,EACb,OAAO,GAAE;IAAE,aAAa,CAAC,EAAE,OAAO,CAAA;CAAO,GACxC,aAAa,GAAG,IAAI,CA2EtB;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,aAAa;IAC5B,yDAAyD;IACzD,MAAM,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAClE,yEAAyE;IACzE,oBAAoB,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAC9D,2EAA2E;IAC3E,oBAAoB,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CAC7D;AAED,wBAAgB,aAAa,CAC3B,MAAM,EAAE,kBAAkB,EAC1B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC7B,aAAa,CAsBf"}

package/dist/measured-profile.js

@@ -55,6 +55,7 @@ export function measuredUsage(report, label, options = {}) {
     const outputTokens = slices.reduce((sum, row) => sum + row.breakdown.outputTokens, 0);
     const inputTokens = slices.reduce((sum, row) => sum + row.breakdown.inputTokens, 0);
     const cacheReadTokens = slices.reduce((sum, row) => sum + row.breakdown.cacheReadTokens, 0);
+    const cacheWriteTokens = slices.reduce((sum, row) => sum + row.breakdown.cacheWriteTokens, 0);
     // The model carrying the most spend. Ties break on the larger call count, so
     // the answer is stable rather than dependent on map ordering.
     const ranked = [...slices].sort((a, b) => b.breakdown.totalUsd - a.breakdown.totalUsd || b.breakdown.calls - a.breakdown.calls);
@@ -69,7 +70,27 @@ export function measuredUsage(report, label, options = {}) {
     const scaled = spanDays !== null && spanDays >= MIN_SCALE_DAYS
         ? { fromDays: spanDays, factor: SCALE_TO_DAYS / spanDays }
         : null;
-    const readShare = inputTokens + cacheReadTokens > 0 ? cacheReadTokens / (inputTokens + cacheReadTokens) : 0;
+    /**
+     * Every input token in the denominator, writes included.
+     *
+     * This was `reads / (input + reads)`, which leaves cache *writes* out of the
+     * total it is a share of. A workload that rewrites its prefix on every call
+     * and reads it back rarely then reports a **high** hit rate: with 100 read
+     * tokens, no plain input and 10,000 written, the old expression answers 100%
+     * where the truth is 1%.
+     *
+     * That is the worst direction for this number to be wrong in. It is handed
+     * to `optimize` as `cacheHitRate`, which decides whether caching is paying
+     * off — so the shape that is burning money on writes was the shape most
+     * likely to be told its cache was working perfectly.
+     *
+     * Writes are input tokens: they are billed at the input rate times the write
+     * multiplier, they arrive in the same `usage` block, and any accounting of
+     * "what share of the input came from cache" that omits them is answering a
+     * narrower question than the one it is named for.
+     */
+    const allInputTokens = inputTokens + cacheReadTokens + cacheWriteTokens;
+    const readShare = allInputTokens > 0 ? cacheReadTokens / allInputTokens : 0;
     return {
         profile: {
             model: chosen.model,

package/dist/measured-profile.js.map

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

package/dist/pricing.d.ts

@@ -7,7 +7,33 @@ import type { ModelPricing } from './types.js';
  * Amazon Bedrock and Vertex AI pricing is set by each partner and is NOT the
  * pricing in this table.
  */
-export declare const PRICING_LAST_REVIEWED = "2026-06-24";
+/**
+ * When each provider's prices were last checked against that provider's own
+ * published table.
+ *
+ * One date for the whole catalogue was the wrong shape, and it cost a real
+ * error. Seven providers publish independently and are checked independently;
+ * a single date forces a partial review to either overstate itself by moving
+ * the date for everyone, or throw itself away by leaving it. What happened is
+ * the second: this constant was written on 2026-08-04 already reading
+ * 2026-06-24, and never moved again.
+ *
+ * Meanwhile Anthropic cancelled the increase that was going to take Sonnet 5
+ * from its 2/10 introductory price to 3/15 on 2026-09-01, and made 2/10
+ * standard. The catalogue still carried the promotion with its end date, so on
+ * 2026-09-01 every Sonnet 5 figure this tool printed would have risen 50% with
+ * no code change and no way for a reader to tell. A price nobody charges is
+ * the one error this product cannot make, and it was four days out on a timer.
+ *
+ * So: a date per provider, checked against that provider's own page, and the
+ * catalogue's headline date derived as the oldest of them rather than typed.
+ */
+export declare const PROVIDER_REVIEWED: Readonly<Record<string, string>>;
+/**
+ * The catalogue's age is its oldest provider's, because a reader asking how
+ * old this table is wants the answer for the worst part of it, not the best.
+ */
+export declare const PRICING_LAST_REVIEWED: string;
 /** Cost multipliers relative to the input price. */
 /**
  * The defaults, which are Anthropic's numbers.
@@ -75,6 +101,25 @@ export interface PricingCatalogue {
 export declare function indexModels(models: ModelPricing[]): Map<string, ModelPricing>;
 /** The prices compiled into this release. */
 export declare const BUNDLED_CATALOGUE: PricingCatalogue;
+/**
+ * Whether this model may be offered to a reader as something to move to.
+ *
+ * One home for a two-part rule that used to be written in four places as one
+ * part. `recommendable: false` — a private programme, a waitlist — was honoured
+ * at every one of them. `retired` is the stronger statement: the provider
+ * answered a real request for the id with an error, so a switch to it is not a
+ * worse recommendation, it is one that cannot be carried out at all.
+ *
+ * Written as a function rather than as a second `&&` at four call sites,
+ * because the fifth call site is always the one that gets written with only the
+ * first half. `pricing.test.js` fails a source file that filters on
+ * `recommendable` without coming through here, and that guard was proved by
+ * planting exactly that filter.
+ *
+ * Pricing is a separate question and stays answered: a retired model keeps its
+ * price, because a log full of its calls records money that was really spent.
+ */
+export declare function isOffered(model: ModelPricing): boolean;
 /** Looks a model up in a specific catalogue. */
 export declare function modelFrom(catalogue: PricingCatalogue, id: string): ModelPricing;
 /**
@@ -93,11 +138,46 @@ export declare function cheapestOfTierIn(catalogue: PricingCatalogue, tier: Mode
 provider?: string): ModelPricing;
 export declare function getModel(id: string): ModelPricing;
 export declare function listModels(): ModelPricing[];
-export declare function effectivePricing(model: ModelPricing, on?: Date): {
+/** Effective price on a given date, applying any live promotion. */
+/**
+ * Memoised per model, because this runs once per record when a usage log is
+ * priced: a 200k-line profile called it 200k times, and the `new Date(...)`
+ * parse of the promo's end date alone was 0.7 of the 2.4 seconds the whole
+ * profile took — measured with --cpu-prof, not guessed. The cache keys on
+ * the model object (a WeakMap, so an overlay's models are collected with
+ * the overlay) and stores the parsed end-of-promo instant plus the two
+ * possible answers; `on` still decides which answer applies on every call,
+ * so behaviour is unchanged to the millisecond.
+ */
+interface Rates {
     inputPerMTok: number;
     outputPerMTok: number;
     promoApplied: boolean;
-};
+    tier: {
+        applied: string | null;
+        decided: boolean;
+        because: string;
+    } | null;
+}
+/**
+ * What one call is billed at, and what decided it.
+ *
+ * `tier` is the field this grew for, and it carries three states rather than
+ * two. A model with no tiers gets `null`. A model whose condition could be
+ * evaluated gets the tier that applied, or the base rate with `applied: null`
+ * and `decided: true`. A model whose condition could **not** be evaluated —
+ * a size tier priced without a token count — gets `decided: false`, the
+ * **dearer** of the candidate rates, and `because` naming what would settle it.
+ *
+ * The dearer one is not a shrug. A cost figure that is a ceiling can prove
+ * "under budget" and can never surprise a bill; a floor chosen for looking
+ * better is the flattering direction this product spends its time refusing.
+ * The reader still has to be told, which is what `decided: false` is for, and
+ * `pricing.test.js` fails a tiered model whose report drops it.
+ */
+export declare function effectivePricing(model: ModelPricing, on?: Date, context?: {
+    inputTokens?: number;
+}): Rates;
 /** Cheapest model of each capability tier, for recommendations. */
 export declare function cheapestOfTier(tier: ModelPricing['tier']): ModelPricing;
 /**
@@ -116,5 +196,20 @@ export declare function cheapestOfTier(tier: ModelPricing['tier']): ModelPricing
  * a date — an overlay supplies this string, and a wrong one should read as
  * unknown rather than as a confident number computed from `NaN`.
  */
+/**
+ * The age at which this product stops treating its own price table as current.
+ *
+ * Three surfaces warn a reader that the figures above may be off — `profile`,
+ * the MCP report, the browser's bill — and each of them had typed `45` into
+ * its own comparison, with four locale sentences stating it again in prose.
+ * Seven copies of one claim, and nothing that would notice when they
+ * disagreed; the sentence a reader sees names the number, so a drift between
+ * them would have been a surface telling the reader one threshold and applying
+ * another.
+ *
+ * The value is what those surfaces already published, not a new judgement.
+ */
+export declare const STALE_PRICING_DAYS = 45;
 export declare function reviewAgeDays(lastReviewed: string, now: Date): number | null;
+export {};
 //# sourceMappingURL=pricing.d.ts.map

package/dist/pricing.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pricing.d.ts","sourceRoot":"","sources":["../src/pricing.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE/C;;;;;;;GAOG;AACH,eAAO,MAAM,qBAAqB,eAAe,CAAC;AAElD,oDAAoD;AACpD;;;;;;;;GAQG;AACH,eAAO,MAAM,gBAAgB;IAC3B,uCAAuC;aACvC,YAAY,EAAE,IAAI;IAClB,qCAAqC;aACrC,YAAY,EAAE,CAAG;IACjB,2CAA2C;aAC3C,SAAS,EAAE,GAAG;IACd,mDAAmD;aACnD,KAAK,EAAE,GAAG;CACF,CAAC;AAeX,wBAAgB,cAAc,CAAC,KAAK,EAAE,YAAY,GAAG;IACnD,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB,CAYA;AAED,eAAO,MAAM,MAAM,EAAE,YAAY,EAqQhC,CAAC;AAEF,eAAO,MAAM,aAAa,kBAAkB,CAAC;AAE7C;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,YAAY,EAAE,CAAC;IACvB,IAAI,EAAE,GAAG,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IAChC,+DAA+D;IAC/D,YAAY,EAAE,MAAM,CAAC;IACrB,+EAA+E;IAC/E,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,0EAA0E;IAC1E,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,YAAY,EAAE,GAAG,GAAG,CAAC,MAAM,EAAE,YAAY,CAAC,CAK7E;AAiBD,6CAA6C;AAC7C,eAAO,MAAM,iBAAiB,EAAE,gBAA+D,CAAC;AAEhG,gDAAgD;AAChD,wBAAgB,SAAS,CAAC,SAAS,EAAE,gBAAgB,EAAE,EAAE,EAAE,MAAM,GAAG,YAAY,CAQ/E;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,SAAS,EAAE,gBAAgB,EAC3B,IAAI,EAAE,YAAY,CAAC,MAAM,CAAC,EAC1B,EAAE,GAAE,IAAiB;AACrB;;;;;GAKG;AACH,QAAQ,CAAC,EAAE,MAAM,GAChB,YAAY,CAcd;AAED,wBAAgB,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,YAAY,CAEjD;AAED,wBAAgB,UAAU,IAAI,YAAY,EAAE,CAE3C;AAsBD,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,YAAY,EACnB,EAAE,GAAE,IAAiB,GACpB;IAAE,YAAY,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,OAAO,CAAA;CAAE,CAuBxE;AAED,mEAAmE;AACnE,wBAAgB,cAAc,CAAC,IAAI,EAAE,YAAY,CAAC,MAAM,CAAC,GAAG,YAAY,CAKvE;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,aAAa,CAAC,YAAY,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,GAAG,MAAM,GAAG,IAAI,CAU5E"}
+{"version":3,"file":"pricing.d.ts","sourceRoot":"","sources":["../src/pricing.ts"],"names":[],"mappings":"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"}