@trendyvideo/billing 1.2.1 → 1.4.0

package/dist/pricing.d.ts

@@ -6,26 +6,107 @@ export declare const MODEL_PRICING: Record<string, ModelPricing>;
  */
 export declare const DEFAULT_PRICING: ModelPricing;
 /**
- * Look up pricing for a model. Tries exact match first, then prefix match
- * (stripping date suffixes like `-20250514`), then falls back to DEFAULT_PRICING.
+ * Look up the raw pricing row for a model, ignoring any scheduled change.
+ * Tries exact match first, then prefix match, then strips a trailing date
+ * suffix (like `-20250514`). Returns `undefined` when nothing matches.
  */
-export declare function getPricing(model: string): ModelPricing;
+export declare function findPricingRow(model: string): ModelPricing | undefined;
 /**
- * Markup applied to all API costs to ensure profit margin.
- * 1.5x means we charge 50% more than raw cost → ~33% margin.
- * Applied to both token-based costs AND flat-rate overrides.
+ * Look up pricing for a model as of `at` (default: now). Resolution order is
+ * exact match, prefix match, date-suffix strip, then DEFAULT_PRICING.
+ * Rows with a `scheduledChange` return the scheduled rates once `at` reaches
+ * the effective date.
+ */
+export declare function getPricing(model: string, at?: Date): ModelPricing;
+/**
+ * Does this provider report cached tokens as a SUBSET of `inputTokens`?
+ *
+ * Gemini's `usageMetadata.promptTokenCount` already includes
+ * `cachedContentTokenCount`, and the provider forwards them as
+ * `inputTokens` / `cacheReadTokens` unchanged. Anthropic reports
+ * `input_tokens` and `cache_read_input_tokens` disjointly. Billing the
+ * Gemini pair with the Anthropic formula charges every cached token twice
+ * (once at the input rate inside `inputTokens`, again at the cache-read
+ * rate). See docs/architecture/gemini-cache-with-tools.md §5.
+ */
+export declare function promptTokensIncludeCacheReads(model: string): boolean;
+/**
+ * Margin applied to every charge. 1.5x means the customer pays 50% more than
+ * the provider charges us (~33% margin).
+ *
+ * WHERE it is applied (Sully, 2026-09-04: "token to credit should be exact,
+ * markup after conversion"): to the CREDIT figure, in `calculateBilledCredits`,
+ * after the exact microdollar-to-credit conversion. It is NEVER applied to
+ * `cost_microdollars`: that column stores the true provider cost so it
+ * reconciles against Google's and Anthropic's invoices. `recordUsage` is the
+ * only writer and runs the two steps in that order.
+ *
+ * History: 1.0.0 to 1.2.1 multiplied inside `calculateCostMicrodollars`, so
+ * the margin was baked into the stored cost. #118 made that function return
+ * raw cost and nothing picked the markup back up (zero margin, never
+ * published). PR #255 first restored it on the microdollar side; this
+ * revision moves it to the credit side per the decision above.
+ *
+ * Callers that pass a `costMicrodollarsOverride` (voice, Seedance, image gen,
+ * music) pass the RAW provider cost. It is stored as-is and marked up on the
+ * credit side like everything else.
  */
 export declare const COST_MARKUP = 1.5;
 /**
- * Calculate cost in microdollars (1 microdollar = $0.000001).
+ * True provider cost in microdollars (1 microdollar = $0.000001), NO markup.
  *
  * Since pricing is per-million tokens:
  *   cost_usd = (tokens / 1_000_000) * rate_per_million
  *   cost_microdollars = cost_usd * 1_000_000 = tokens * rate_per_million
  *
- * All costs include COST_MARKUP (1.5x) for profit margin.
+ * This is what Google or Anthropic invoices us and what `recordUsage` stores
+ * in `usage_events.cost_microdollars`. It is NOT what the customer is
+ * charged: `calculateBilledCredits` derives `credits_consumed` from it.
+ *
+ * Rounding: the exact figure is rounded to the nearest whole microdollar
+ * because the column is `bigint`. Maximum error 0.5 µ$ ($0.0000005), below
+ * any invoice's precision. An override gets the same treatment (callers pass
+ * integers, so in practice it passes through untouched). The full rounding
+ * rule for a charge is documented once, on `calculateBilledCredits`.
+ */
+export declare function calculateCostMicrodollars(model: string, inputTokens: number, outputTokens: number, cacheReadTokens?: number, cacheCreationTokens?: number, costMicrodollarsOverride?: number, at?: Date): number;
+export type GeminiEmbedding2Modality = 'text' | 'image' | 'audio' | 'video';
+/** USD per 1M input tokens, by modality. */
+export declare const GEMINI_EMBEDDING_2_INPUT_PRICING: Record<GeminiEmbedding2Modality, number>;
+/** Per-unit equivalents (raw microdollars) for when the API reports no token count. */
+export declare const GEMINI_EMBEDDING_2_UNIT_RATES: {
+    readonly microdollarsPerImage: 120;
+    readonly microdollarsPerAudioSecond: 160;
+    readonly microdollarsPerVideoFrame: 790;
+    readonly videoMaxFrames: 32;
+    /** Rough text fallback: ~4 chars per token. */
+    readonly charsPerTextToken: 4;
+};
+/** Frames Google samples from a video of `durationSec` (1 fps, capped at 32). */
+export declare function geminiEmbedding2VideoFrames(durationSec: number): number;
+export interface GeminiEmbedding2CostInput {
+    modality: GeminiEmbedding2Modality;
+    /** `usageMetadata.promptTokenCount` from the embedContent response, when present. */
+    promptTokens?: number | undefined;
+    /** Fallback inputs, used only when `promptTokens` is absent. */
+    textChars?: number | undefined;
+    imageCount?: number | undefined;
+    durationSec?: number | undefined;
+}
+export interface GeminiEmbedding2Cost {
+    /** RAW microdollars — pass as `costMicrodollarsOverride`; COST_MARKUP is applied by recordUsage. */
+    costMicrodollars: number;
+    /** Token count to store as `inputTokens` (reported, or estimated for text). 0 when unknown. */
+    inputTokens: number;
+    basis: 'reported_tokens' | 'estimated_units';
+}
+/**
+ * Raw cost of one `gemini-embedding-2:embedContent` call. Prefers the token
+ * count Google reports; otherwise falls back to the published per-unit rate
+ * for the modality. Always returns a cost for a non-empty input so a call can
+ * never be recorded as free by accident.
  */
-export declare function calculateCostMicrodollars(model: string, inputTokens: number, outputTokens: number, cacheReadTokens?: number, cacheCreationTokens?: number, costMicrodollarsOverride?: number): number;
+export declare function calculateGeminiEmbedding2CostMicrodollars(input: GeminiEmbedding2CostInput): GeminiEmbedding2Cost;
 export interface MediaRate {
     /** Pricing shape: per-unit (e.g. one image) or per-second (e.g. a video clip). */
     unit: 'per_clip' | 'per_second';
@@ -38,8 +119,9 @@ export declare const MEDIA_RATE_PRICING: Record<string, MediaRate>;
 /**
  * Estimate the RAW microdollar cost of a media-generation call before
  * COST_MARKUP is applied. Callers pass the result as
- * `costMicrodollarsOverride` into `recordUsage`; the markup is applied
- * inside `calculateCostMicrodollars`.
+ * `costMicrodollarsOverride` into `recordUsage`, which stores it as the
+ * row's `cost_microdollars` and applies the markup on the credit side via
+ * `calculateBilledCredits`.
  *
  * - For `per_clip` rates, pass `units` (default 1).
  * - For `per_second` rates, pass `durationSec`.
@@ -52,15 +134,70 @@ export declare function estimateMediaCostMicrodollars(model: string, opts?: {
     units?: number;
 }): number;
 /**
- * Same estimate but with COST_MARKUP applied — i.e. what the user is
- * actually billed. Use this for cost-preview UIs that need to match
- * the final `usage_events.credits_consumed` write.
+ * Same estimate with COST_MARKUP applied, still in microdollars: what the
+ * user is billed, expressed as credits × 10,000. Use it for cost-preview
+ * UIs. `microdollarsToCredits` of this value equals the `credits_consumed`
+ * that `recordUsage` writes for the raw estimate, to the 0.01 credit, for
+ * every rate in the table (tests in usage-tracker.test.ts). It is NOT what
+ * `cost_microdollars` stores; that column holds the raw estimate.
  */
 export declare function estimateBilledMediaCostMicrodollars(model: string, opts?: {
     durationSec?: number;
     units?: number;
 }): number;
 export declare const MICRODOLLARS_PER_CREDIT = 10000;
+/**
+ * Trendy Voice (Gemini Live) per-minute billing rate.
+ *
+ *   12 credits = $0.12 = 120,000 microdollars per session-minute.
+ *
+ * Minutes are rounded UP — partial minutes are billed as a full minute.
+ * Fairness goes to Trendy on the round-up; very short sessions (<10s)
+ * are not billed at all (see the meter's startup guard).
+ */
+export declare const TRENDY_VOICE_CREDITS_PER_MINUTE = 12;
+export declare const TRENDY_VOICE_MICRODOLLARS_PER_MINUTE: number;
+export declare const TRENDY_VOICE_SKU: "trendy_voice_minute";
+/**
+ * Precision of `usage_events.credits_consumed` (`numeric(12,2)`): charges are
+ * kept to 0.01 credit = 100 µ$ = $0.0001.
+ */
+export declare const CREDIT_DECIMALS = 2;
+/** Exact conversion. No rounding, no markup. */
 export declare function microdollarsToCredits(microdollars: number): number;
 export declare function creditsToMicrodollars(credits: number): number;
+/**
+ * Customer-billed credits for a true-cost `costMicrodollars` figure. This is
+ * the ONLY place COST_MARKUP is applied and the ONLY place a charge is
+ * rounded. `recordUsage` writes the result to `credits_consumed`.
+ *
+ *   billed credits = round2( (cost_microdollars / 10,000) × COST_MARKUP )
+ *
+ *   1. exact conversion   cost_microdollars / MICRODOLLARS_PER_CREDIT
+ *   2. margin             × COST_MARKUP
+ *   3. one rounding       half up, to 0.01 credit (CREDIT_DECIMALS), so the
+ *                         value passed to the RPC is the value stored and
+ *                         SQL reproduces it exactly:
+ *                         ROUND(cost_microdollars * 1.5 / 10000, 2)
+ *
+ * THE ROUNDING RULE, in full. Nothing else in this package rounds a charge.
+ *   - `cost_microdollars`: nearest whole microdollar (bigint column), in
+ *     `calculateCostMicrodollars`. A storage step, not a pricing step.
+ *   - `credits_consumed`: here, once, half up, to 0.01 credit, computed from
+ *     the stored `cost_microdollars` so every row is self-consistent.
+ *   - No rounding up to a whole credit (1.2.1 did that with Math.ceil), no
+ *     rounding before the markup, no rounding in `microdollarsToCredits`.
+ *   - A charge below 0.005 credit (true cost of 33 µ$ or less) rounds to
+ *     0.00. The `record_usage_atomic` RPC then falls back to
+ *     ROUND(cost_microdollars / 10000, 2), which is also 0.00 for every such
+ *     value, so the two never disagree (test in pricing.test.ts).
+ *
+ * Implementation note: steps 1 and 2 commute, and the arithmetic is done in
+ * whole microdollars (`cost × 1.5` is exact for any integer) before the one
+ * division, because `1500 / 10000 * 1.5` is 0.224999… in floating point and
+ * would round to 0.22 instead of 0.23. `pricing.test.ts` checks the result
+ * against an integer reference implementation for every value up to
+ * 5,000,000 µ$ and a set of larger ones.
+ */
+export declare function calculateBilledCredits(costMicrodollars: number): number;
 //# 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,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAOvC,eAAO,MAAM,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAkDtD,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,eAAe,EAAE,YAK7B,CAAC;AAEF;;;GAGG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,YAAY,CAgBtD;AAED;;;;GAIG;AACH,eAAO,MAAM,WAAW,MAAM,CAAC;AAE/B;;;;;;;;GAQG;AACH,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,MAAM,EACb,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,MAAM,EACpB,eAAe,SAAI,EACnB,mBAAmB,SAAI,EACvB,wBAAwB,CAAC,EAAE,MAAM,GAChC,MAAM,CAaR;AAaD,MAAM,WAAW,SAAS;IACxB,kFAAkF;IAClF,IAAI,EAAE,UAAU,GAAG,YAAY,CAAC;IAChC,yCAAyC;IACzC,mBAAmB,EAAE,MAAM,CAAC;IAC5B,yEAAyE;IACzE,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,eAAO,MAAM,kBAAkB,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CA2CxD,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,wBAAgB,6BAA6B,CAC3C,KAAK,EAAE,MAAM,EACb,IAAI,GAAE;IAAE,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAO,GAClD,MAAM,CASR;AAED;;;;GAIG;AACH,wBAAgB,mCAAmC,CACjD,KAAK,EAAE,MAAM,EACb,IAAI,GAAE;IAAE,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAO,GAClD,MAAM,CAER;AAMD,eAAO,MAAM,uBAAuB,QAAS,CAAC;AAE9C,wBAAgB,qBAAqB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAElE;AAED,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAE7D"}
+{"version":3,"file":"pricing.d.ts","sourceRoot":"","sources":["../src/pricing.ts"],"names":[],"mappings":"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"}