@vibesdotdev/account 0.0.0-stage → 1.0.0-rc.3

package/dist/billing/rating/schemas/cost-basis.d.ts

@@ -0,0 +1,62 @@
+import * as z from 'zod/v4';
+/** Canonical measurable units for provider/resource cost-basis metadata. */
+export declare const costBasisUnitsSchema: z.ZodEnum<{
+    request: "request";
+    image: "image";
+    input_tokens: "input_tokens";
+    output_tokens: "output_tokens";
+    cached_input_tokens: "cached_input_tokens";
+    cache_write_5m_tokens: "cache_write_5m_tokens";
+    cache_write_1h_tokens: "cache_write_1h_tokens";
+    audio_minute: "audio_minute";
+    gb_month: "gb_month";
+    gb_egress: "gb_egress";
+    compute_second: "compute_second";
+    gpu_second: "gpu_second";
+}>;
+export type CostBasisUnits = z.infer<typeof costBasisUnitsSchema>;
+export declare const costBasisSourceSchema: z.ZodEnum<{
+    published: "published";
+    manual: "manual";
+    measured: "measured";
+    heuristic: "heuristic";
+}>;
+export type CostBasisSource = z.infer<typeof costBasisSourceSchema>;
+export declare const costBasisConfidenceSchema: z.ZodEnum<{
+    low: "low";
+    medium: "medium";
+    high: "high";
+}>;
+export type CostBasisConfidence = z.infer<typeof costBasisConfidenceSchema>;
+export declare const costBasisSchema: z.ZodObject<{
+    units: z.ZodEnum<{
+        request: "request";
+        image: "image";
+        input_tokens: "input_tokens";
+        output_tokens: "output_tokens";
+        cached_input_tokens: "cached_input_tokens";
+        cache_write_5m_tokens: "cache_write_5m_tokens";
+        cache_write_1h_tokens: "cache_write_1h_tokens";
+        audio_minute: "audio_minute";
+        gb_month: "gb_month";
+        gb_egress: "gb_egress";
+        compute_second: "compute_second";
+        gpu_second: "gpu_second";
+    }>;
+    usdPerMillionUnits: z.ZodOptional<z.ZodNumber>;
+    usdPerUnit: z.ZodOptional<z.ZodNumber>;
+    source: z.ZodEnum<{
+        published: "published";
+        manual: "manual";
+        measured: "measured";
+        heuristic: "heuristic";
+    }>;
+    confidence: z.ZodEnum<{
+        low: "low";
+        medium: "medium";
+        high: "high";
+    }>;
+    effectiveAt: z.ZodString;
+}, z.core.$strip>;
+export type CostBasis = z.infer<typeof costBasisSchema>;
+//# sourceMappingURL=cost-basis.d.ts.map

package/dist/billing/rating/schemas/cost-basis.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cost-basis.d.ts","sourceRoot":"","sources":["../../../../src/billing/rating/schemas/cost-basis.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,QAAQ,CAAC;AAE5B,4EAA4E;AAC5E,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;EAa/B,CAAC;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAElE,eAAO,MAAM,qBAAqB;;;;;EAA2D,CAAC;AAC9F,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEpE,eAAO,MAAM,yBAAyB;;;;EAAoC,CAAC;AAC3E,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAE5E,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAY1B,CAAC;AAEH,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC"}

package/dist/billing/rating/schemas/cost-basis.js

@@ -0,0 +1,29 @@
+import * as z from 'zod/v4';
+/** Canonical measurable units for provider/resource cost-basis metadata. */
+export const costBasisUnitsSchema = z.enum([
+    'input_tokens',
+    'output_tokens',
+    'cached_input_tokens',
+    'cache_write_5m_tokens',
+    'cache_write_1h_tokens',
+    'image',
+    'audio_minute',
+    'request',
+    'gb_month',
+    'gb_egress',
+    'compute_second',
+    'gpu_second'
+]);
+export const costBasisSourceSchema = z.enum(['published', 'measured', 'heuristic', 'manual']);
+export const costBasisConfidenceSchema = z.enum(['high', 'medium', 'low']);
+export const costBasisSchema = z
+    .object({
+    units: costBasisUnitsSchema,
+    usdPerMillionUnits: z.number().nonnegative().optional(),
+    usdPerUnit: z.number().nonnegative().optional(),
+    source: costBasisSourceSchema,
+    confidence: costBasisConfidenceSchema,
+    effectiveAt: z.string().datetime()
+})
+    .refine((value) => value.usdPerMillionUnits !== undefined || value.usdPerUnit !== undefined, { message: 'CostBasis requires usdPerMillionUnits or usdPerUnit' });
+//# sourceMappingURL=cost-basis.js.map

package/dist/billing/rating/schemas/cost-basis.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cost-basis.js","sourceRoot":"","sources":["../../../../src/billing/rating/schemas/cost-basis.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,QAAQ,CAAC;AAE5B,4EAA4E;AAC5E,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,CAAC,IAAI,CAAC;IAC1C,cAAc;IACd,eAAe;IACf,qBAAqB;IACrB,uBAAuB;IACvB,uBAAuB;IACvB,OAAO;IACP,cAAc;IACd,SAAS;IACT,UAAU;IACV,WAAW;IACX,gBAAgB;IAChB,YAAY;CACZ,CAAC,CAAC;AAGH,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,WAAW,EAAE,UAAU,EAAE,WAAW,EAAE,QAAQ,CAAC,CAAC,CAAC;AAG9F,MAAM,CAAC,MAAM,yBAAyB,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,QAAQ,EAAE,KAAK,CAAC,CAAC,CAAC;AAG3E,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC;KAC9B,MAAM,CAAC;IACP,KAAK,EAAE,oBAAoB;IAC3B,kBAAkB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,WAAW,EAAE,CAAC,QAAQ,EAAE;IACvD,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,WAAW,EAAE,CAAC,QAAQ,EAAE;IAC/C,MAAM,EAAE,qBAAqB;IAC7B,UAAU,EAAE,yBAAyB;IACrC,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CAClC,CAAC;KACD,MAAM,CACN,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,kBAAkB,KAAK,SAAS,IAAI,KAAK,CAAC,UAAU,KAAK,SAAS,EACnF,EAAE,OAAO,EAAE,qDAAqD,EAAE,CAClE,CAAC"}

package/dist/billing/rating/schemas/credit-pool.d.ts

@@ -0,0 +1,82 @@
+import * as z from 'zod/v4';
+/**
+ * Scope restrictions that bind a credit pool to a subset of charges.
+ *
+ * - `features`: charge feature slug must be in this list (e.g. plan
+ *   grants might scope to `['ai-text-tokens','ai-image-generations']`
+ *   so monthly credits can't be drained on bandwidth).
+ * - `hardware`: charge hardware path must match (e.g. an
+ *   infrastructure-credits pool scoped to `'cloud'`).
+ * - `surfaces`: emitting surface must match (e.g. a chat-only promo).
+ * - `expiresAt`: ISO timestamp after which this pool is ignored. Plan
+ *   grants typically set this to the end of the billing period.
+ *
+ * A `null` scope means general-purpose: spendable on any charge. Credit
+ * packs and refunds typically have `null` scope.
+ */
+export declare const creditPoolScopeSchema: z.ZodObject<{
+    features: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    hardware: z.ZodOptional<z.ZodEnum<{
+        consumer: "consumer";
+        cloud: "cloud";
+        hybrid: "hybrid";
+    }>>;
+    surfaces: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    expiresAt: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type CreditPoolScope = z.infer<typeof creditPoolScopeSchema>;
+export declare const creditPoolOwnerKindSchema: z.ZodEnum<{
+    user: "user";
+    organization: "organization";
+}>;
+export type CreditPoolOwnerKind = z.infer<typeof creditPoolOwnerKindSchema>;
+export declare const creditPoolSourceSchema: z.ZodEnum<{
+    purchase: "purchase";
+    refund: "refund";
+    "plan-grant": "plan-grant";
+    promo: "promo";
+    marketplace: "marketplace";
+}>;
+export type CreditPoolSource = z.infer<typeof creditPoolSourceSchema>;
+/**
+ * A bucket of credits owned by a user or organization. The ledger
+ * resolves charges by walking pools in spending priority:
+ *
+ *   1. expiring scoped pools, soonest first (use it or lose it)
+ *   2. non-expiring scoped pools, most-restrictive scope first
+ *   3. general-purpose pools (scope = null)
+ *
+ * Charges may split across multiple pools when no single pool covers
+ * the full cost; each split writes a separate ledger row stamped with
+ * the originating pool id.
+ */
+export declare const creditPoolSchema: z.ZodObject<{
+    id: z.ZodString;
+    ownerKind: z.ZodEnum<{
+        user: "user";
+        organization: "organization";
+    }>;
+    ownerId: z.ZodString;
+    balance: z.ZodNumber;
+    scope: z.ZodNullable<z.ZodObject<{
+        features: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        hardware: z.ZodOptional<z.ZodEnum<{
+            consumer: "consumer";
+            cloud: "cloud";
+            hybrid: "hybrid";
+        }>>;
+        surfaces: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        expiresAt: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    source: z.ZodEnum<{
+        purchase: "purchase";
+        refund: "refund";
+        "plan-grant": "plan-grant";
+        promo: "promo";
+        marketplace: "marketplace";
+    }>;
+    createdAt: z.ZodString;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+export type CreditPool = z.infer<typeof creditPoolSchema>;
+//# sourceMappingURL=credit-pool.d.ts.map

package/dist/billing/rating/schemas/credit-pool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"credit-pool.d.ts","sourceRoot":"","sources":["../../../../src/billing/rating/schemas/credit-pool.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,QAAQ,CAAC;AAG5B;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,qBAAqB;;;;;;;;;iBAKhC,CAAC;AAEH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEpE,eAAO,MAAM,yBAAyB;;;EAAmC,CAAC;AAC1E,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAE5E,eAAO,MAAM,sBAAsB;;;;;;EAMjC,CAAC;AAEH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAEtE;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAS3B,CAAC;AAEH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC"}

package/dist/billing/rating/schemas/credit-pool.js

@@ -0,0 +1,54 @@
+import * as z from 'zod/v4';
+import { hardwarePathSchema } from "./rated-usage.js";
+/**
+ * Scope restrictions that bind a credit pool to a subset of charges.
+ *
+ * - `features`: charge feature slug must be in this list (e.g. plan
+ *   grants might scope to `['ai-text-tokens','ai-image-generations']`
+ *   so monthly credits can't be drained on bandwidth).
+ * - `hardware`: charge hardware path must match (e.g. an
+ *   infrastructure-credits pool scoped to `'cloud'`).
+ * - `surfaces`: emitting surface must match (e.g. a chat-only promo).
+ * - `expiresAt`: ISO timestamp after which this pool is ignored. Plan
+ *   grants typically set this to the end of the billing period.
+ *
+ * A `null` scope means general-purpose: spendable on any charge. Credit
+ * packs and refunds typically have `null` scope.
+ */
+export const creditPoolScopeSchema = z.object({
+    features: z.array(z.string()).optional(),
+    hardware: hardwarePathSchema.optional(),
+    surfaces: z.array(z.string()).optional(),
+    expiresAt: z.string().datetime().optional()
+});
+export const creditPoolOwnerKindSchema = z.enum(['user', 'organization']);
+export const creditPoolSourceSchema = z.enum([
+    'plan-grant',
+    'purchase',
+    'promo',
+    'refund',
+    'marketplace'
+]);
+/**
+ * A bucket of credits owned by a user or organization. The ledger
+ * resolves charges by walking pools in spending priority:
+ *
+ *   1. expiring scoped pools, soonest first (use it or lose it)
+ *   2. non-expiring scoped pools, most-restrictive scope first
+ *   3. general-purpose pools (scope = null)
+ *
+ * Charges may split across multiple pools when no single pool covers
+ * the full cost; each split writes a separate ledger row stamped with
+ * the originating pool id.
+ */
+export const creditPoolSchema = z.object({
+    id: z.string().uuid(),
+    ownerKind: creditPoolOwnerKindSchema,
+    ownerId: z.string().min(1),
+    balance: z.number().nonnegative(),
+    scope: creditPoolScopeSchema.nullable(),
+    source: creditPoolSourceSchema,
+    createdAt: z.string().datetime(),
+    metadata: z.record(z.string(), z.unknown()).optional()
+});
+//# sourceMappingURL=credit-pool.js.map

package/dist/billing/rating/schemas/credit-pool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"credit-pool.js","sourceRoot":"","sources":["../../../../src/billing/rating/schemas/credit-pool.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,QAAQ,CAAC;AAC5B,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAEtD;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC7C,QAAQ,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE;IACxC,QAAQ,EAAE,kBAAkB,CAAC,QAAQ,EAAE;IACvC,QAAQ,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE;IACxC,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE;CAC3C,CAAC,CAAC;AAIH,MAAM,CAAC,MAAM,yBAAyB,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC,CAAC;AAG1E,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,CAAC,IAAI,CAAC;IAC5C,YAAY;IACZ,UAAU;IACV,OAAO;IACP,QAAQ;IACR,aAAa;CACb,CAAC,CAAC;AAIH;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,CAAC,MAAM,CAAC;IACxC,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE;IACrB,SAAS,EAAE,yBAAyB;IACpC,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC1B,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,WAAW,EAAE;IACjC,KAAK,EAAE,qBAAqB,CAAC,QAAQ,EAAE;IACvC,MAAM,EAAE,sBAAsB;IAC9B,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAChC,QAAQ,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,QAAQ,EAAE;CACtD,CAAC,CAAC"}

package/dist/billing/rating/schemas/index.d.ts

@@ -0,0 +1,5 @@
+export * from './cost-basis.ts';
+export * from './credit-pool.ts';
+export * from './rated-usage.ts';
+export * from './rating-policy.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/billing/rating/schemas/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/billing/rating/schemas/index.ts"],"names":[],"mappings":"AAAA,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC;AACjC,cAAc,kBAAkB,CAAC;AACjC,cAAc,oBAAoB,CAAC"}

package/dist/billing/rating/schemas/index.js

@@ -0,0 +1,5 @@
+export * from "./cost-basis.js";
+export * from "./credit-pool.js";
+export * from "./rated-usage.js";
+export * from "./rating-policy.js";
+//# sourceMappingURL=index.js.map

package/dist/billing/rating/schemas/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/billing/rating/schemas/index.ts"],"names":[],"mappings":"AAAA,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC;AACjC,cAAc,kBAAkB,CAAC;AACjC,cAAc,oBAAoB,CAAC"}

package/dist/billing/rating/schemas/rated-usage.d.ts

@@ -0,0 +1,205 @@
+import * as z from 'zod/v4';
+/**
+ * Where the work physically executes. Drives the consumer-local-free
+ * rule:
+ * - `consumer`: user's own machine (LM Studio, Ollama, etc.) with no
+ *   vibes cloud resource participating → 0 credits.
+ * - `cloud`: vibes-operated infrastructure (Workers AI, our Anthropic
+ *   key, our DigitalOcean Gradient, our sandbox host) → rated normally.
+ * - `hybrid`: split path (e.g. user's LM Studio plus our relay/storage)
+ *   — only the cloud portion is rated and a second usage event is
+ *   emitted for it; the AI compute portion is still 0.
+ */
+export declare const hardwarePathSchema: z.ZodEnum<{
+    consumer: "consumer";
+    cloud: "cloud";
+    hybrid: "hybrid";
+}>;
+export type HardwarePath = z.infer<typeof hardwarePathSchema>;
+/**
+ * Measured units carried by the emitting surface. Keys must match
+ * `CostBasisUnits` exactly; values are the absolute quantity (NOT
+ * normalized to millions — the rating engine handles the per-million
+ * arithmetic for token units internally).
+ *
+ * Example: `{ input_tokens: 5000, output_tokens: 1200 }` for a chat
+ * response of 1200 output tokens against a 5K-token prompt.
+ */
+export declare const measuredUnitsSchema: z.ZodRecord<z.ZodEnum<{
+    request: "request";
+    image: "image";
+    input_tokens: "input_tokens";
+    output_tokens: "output_tokens";
+    cached_input_tokens: "cached_input_tokens";
+    cache_write_5m_tokens: "cache_write_5m_tokens";
+    cache_write_1h_tokens: "cache_write_1h_tokens";
+    audio_minute: "audio_minute";
+    gb_month: "gb_month";
+    gb_egress: "gb_egress";
+    compute_second: "compute_second";
+    gpu_second: "gpu_second";
+}>, z.ZodNumber>;
+/**
+ * Partial-by-design: a measurement event names ONLY the unit classes it
+ * touches. Token-only generations omit `image`/`gb_month`/etc. and
+ * storage sweeps omit token keys. The Zod schema accepts any subset of
+ * the canonical unit enum; the TS type follows.
+ */
+export type MeasuredUnits = Partial<z.infer<typeof measuredUnitsSchema>>;
+/**
+ * Input to the rating engine. Carries everything the deterministic
+ * `rateUsage()` function needs — nothing about user identity, pool
+ * routing, or persistence (those happen in the account-web ledger
+ * layer that wraps the engine).
+ *
+ * `costBasis` is optional: if absent, the engine falls back to the
+ * `unknownCostHeuristic` policy floors. Callers that know the cost
+ * (provider adapters, model registry lookups) should supply it
+ * explicitly so charges land on `exact` not `heuristic`.
+ */
+export declare const ratedUsageInputSchema: z.ZodObject<{
+    featureSlug: z.ZodString;
+    surface: z.ZodString;
+    hardware: z.ZodEnum<{
+        consumer: "consumer";
+        cloud: "cloud";
+        hybrid: "hybrid";
+    }>;
+    modelId: z.ZodOptional<z.ZodString>;
+    providerId: z.ZodOptional<z.ZodString>;
+    resourceId: z.ZodOptional<z.ZodString>;
+    measuredUnits: z.ZodRecord<z.ZodEnum<{
+        request: "request";
+        image: "image";
+        input_tokens: "input_tokens";
+        output_tokens: "output_tokens";
+        cached_input_tokens: "cached_input_tokens";
+        cache_write_5m_tokens: "cache_write_5m_tokens";
+        cache_write_1h_tokens: "cache_write_1h_tokens";
+        audio_minute: "audio_minute";
+        gb_month: "gb_month";
+        gb_egress: "gb_egress";
+        compute_second: "compute_second";
+        gpu_second: "gpu_second";
+    }>, z.ZodNumber>;
+    costBasis: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        units: z.ZodEnum<{
+            request: "request";
+            image: "image";
+            input_tokens: "input_tokens";
+            output_tokens: "output_tokens";
+            cached_input_tokens: "cached_input_tokens";
+            cache_write_5m_tokens: "cache_write_5m_tokens";
+            cache_write_1h_tokens: "cache_write_1h_tokens";
+            audio_minute: "audio_minute";
+            gb_month: "gb_month";
+            gb_egress: "gb_egress";
+            compute_second: "compute_second";
+            gpu_second: "gpu_second";
+        }>;
+        usdPerMillionUnits: z.ZodOptional<z.ZodNumber>;
+        usdPerUnit: z.ZodOptional<z.ZodNumber>;
+        source: z.ZodEnum<{
+            published: "published";
+            manual: "manual";
+            measured: "measured";
+            heuristic: "heuristic";
+        }>;
+        confidence: z.ZodEnum<{
+            low: "low";
+            medium: "medium";
+            high: "high";
+        }>;
+        effectiveAt: z.ZodString;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type RatedUsageInput = z.infer<typeof ratedUsageInputSchema>;
+/**
+ * Per-unit breakdown of how the cost-basis sum was computed. Preserved
+ * in `RatedUsageResult` so the ledger row can reproduce the charge from
+ * its metadata alone (SPEC §11).
+ */
+export declare const rateBreakdownEntrySchema: z.ZodObject<{
+    unit: z.ZodEnum<{
+        request: "request";
+        image: "image";
+        input_tokens: "input_tokens";
+        output_tokens: "output_tokens";
+        cached_input_tokens: "cached_input_tokens";
+        cache_write_5m_tokens: "cache_write_5m_tokens";
+        cache_write_1h_tokens: "cache_write_1h_tokens";
+        audio_minute: "audio_minute";
+        gb_month: "gb_month";
+        gb_egress: "gb_egress";
+        compute_second: "compute_second";
+        gpu_second: "gpu_second";
+    }>;
+    quantity: z.ZodNumber;
+    usdPerUnit: z.ZodNumber;
+    usdSubtotal: z.ZodNumber;
+    source: z.ZodString;
+}, z.core.$strip>;
+export type RateBreakdownEntry = z.infer<typeof rateBreakdownEntrySchema>;
+/**
+ * Why the engine produced the charge it did. Surfaced in ledger metadata
+ * + admin tooling; not user-facing.
+ */
+export declare const ratingReasonSchema: z.ZodEnum<{
+    rated: "rated";
+    "consumer-local-free": "consumer-local-free";
+    "minimum-charge": "minimum-charge";
+    "heuristic-fallback": "heuristic-fallback";
+    "overrides-applied": "overrides-applied";
+}>;
+export type RatingReason = z.infer<typeof ratingReasonSchema>;
+export declare const costSourceSchema: z.ZodEnum<{
+    exact: "exact";
+    manual: "manual";
+    heuristic: "heuristic";
+}>;
+export type CostSource = z.infer<typeof costSourceSchema>;
+export declare const ratedUsageResultSchema: z.ZodObject<{
+    chargedCredits: z.ZodNumber;
+    costBasisUsd: z.ZodNumber;
+    multiplier: z.ZodNumber;
+    policyVersion: z.ZodString;
+    costSource: z.ZodEnum<{
+        exact: "exact";
+        manual: "manual";
+        heuristic: "heuristic";
+    }>;
+    reason: z.ZodEnum<{
+        rated: "rated";
+        "consumer-local-free": "consumer-local-free";
+        "minimum-charge": "minimum-charge";
+        "heuristic-fallback": "heuristic-fallback";
+        "overrides-applied": "overrides-applied";
+    }>;
+    hardware: z.ZodEnum<{
+        consumer: "consumer";
+        cloud: "cloud";
+        hybrid: "hybrid";
+    }>;
+    rateBreakdown: z.ZodArray<z.ZodObject<{
+        unit: z.ZodEnum<{
+            request: "request";
+            image: "image";
+            input_tokens: "input_tokens";
+            output_tokens: "output_tokens";
+            cached_input_tokens: "cached_input_tokens";
+            cache_write_5m_tokens: "cache_write_5m_tokens";
+            cache_write_1h_tokens: "cache_write_1h_tokens";
+            audio_minute: "audio_minute";
+            gb_month: "gb_month";
+            gb_egress: "gb_egress";
+            compute_second: "compute_second";
+            gpu_second: "gpu_second";
+        }>;
+        quantity: z.ZodNumber;
+        usdPerUnit: z.ZodNumber;
+        usdSubtotal: z.ZodNumber;
+        source: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type RatedUsageResult = z.infer<typeof ratedUsageResultSchema>;
+//# sourceMappingURL=rated-usage.d.ts.map

package/dist/billing/rating/schemas/rated-usage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rated-usage.d.ts","sourceRoot":"","sources":["../../../../src/billing/rating/schemas/rated-usage.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,QAAQ,CAAC;AAG5B;;;;;;;;;;GAUG;AACH,eAAO,MAAM,kBAAkB;;;;EAA0C,CAAC;AAC1E,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAE9D;;;;;;;;GAQG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;gBAA2D,CAAC;AAC5F;;;;;GAKG;AACH,MAAM,MAAM,aAAa,GAAG,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC,CAAC;AAEzE;;;;;;;;;;GAUG;AACH,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAShC,CAAC;AAEH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEpE;;;;GAIG;AACH,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;;;;iBAMnC,CAAC;AAEH,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAE1E;;;GAGG;AACH,eAAO,MAAM,kBAAkB;;;;;;EAM7B,CAAC;AAEH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAE9D,eAAO,MAAM,gBAAgB;;;;EAA2C,CAAC;AACzE,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAE1D,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBASjC,CAAC;AAEH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC"}

package/dist/billing/rating/schemas/rated-usage.js

@@ -0,0 +1,80 @@
+import * as z from 'zod/v4';
+import { costBasisSchema, costBasisUnitsSchema } from "./cost-basis.js";
+/**
+ * Where the work physically executes. Drives the consumer-local-free
+ * rule:
+ * - `consumer`: user's own machine (LM Studio, Ollama, etc.) with no
+ *   vibes cloud resource participating → 0 credits.
+ * - `cloud`: vibes-operated infrastructure (Workers AI, our Anthropic
+ *   key, our DigitalOcean Gradient, our sandbox host) → rated normally.
+ * - `hybrid`: split path (e.g. user's LM Studio plus our relay/storage)
+ *   — only the cloud portion is rated and a second usage event is
+ *   emitted for it; the AI compute portion is still 0.
+ */
+export const hardwarePathSchema = z.enum(['consumer', 'cloud', 'hybrid']);
+/**
+ * Measured units carried by the emitting surface. Keys must match
+ * `CostBasisUnits` exactly; values are the absolute quantity (NOT
+ * normalized to millions — the rating engine handles the per-million
+ * arithmetic for token units internally).
+ *
+ * Example: `{ input_tokens: 5000, output_tokens: 1200 }` for a chat
+ * response of 1200 output tokens against a 5K-token prompt.
+ */
+export const measuredUnitsSchema = z.record(costBasisUnitsSchema, z.number().nonnegative());
+/**
+ * Input to the rating engine. Carries everything the deterministic
+ * `rateUsage()` function needs — nothing about user identity, pool
+ * routing, or persistence (those happen in the account-web ledger
+ * layer that wraps the engine).
+ *
+ * `costBasis` is optional: if absent, the engine falls back to the
+ * `unknownCostHeuristic` policy floors. Callers that know the cost
+ * (provider adapters, model registry lookups) should supply it
+ * explicitly so charges land on `exact` not `heuristic`.
+ */
+export const ratedUsageInputSchema = z.object({
+    featureSlug: z.string().min(1),
+    surface: z.string().min(1),
+    hardware: hardwarePathSchema,
+    modelId: z.string().optional(),
+    providerId: z.string().optional(),
+    resourceId: z.string().optional(),
+    measuredUnits: measuredUnitsSchema,
+    costBasis: z.array(costBasisSchema).optional()
+});
+/**
+ * Per-unit breakdown of how the cost-basis sum was computed. Preserved
+ * in `RatedUsageResult` so the ledger row can reproduce the charge from
+ * its metadata alone (SPEC §11).
+ */
+export const rateBreakdownEntrySchema = z.object({
+    unit: costBasisUnitsSchema,
+    quantity: z.number().nonnegative(),
+    usdPerUnit: z.number().nonnegative(),
+    usdSubtotal: z.number().nonnegative(),
+    source: z.string().min(1)
+});
+/**
+ * Why the engine produced the charge it did. Surfaced in ledger metadata
+ * + admin tooling; not user-facing.
+ */
+export const ratingReasonSchema = z.enum([
+    'rated',
+    'consumer-local-free',
+    'minimum-charge',
+    'heuristic-fallback',
+    'overrides-applied'
+]);
+export const costSourceSchema = z.enum(['exact', 'heuristic', 'manual']);
+export const ratedUsageResultSchema = z.object({
+    chargedCredits: z.number().nonnegative(),
+    costBasisUsd: z.number().nonnegative(),
+    multiplier: z.number().positive(),
+    policyVersion: z.string().min(1),
+    costSource: costSourceSchema,
+    reason: ratingReasonSchema,
+    hardware: hardwarePathSchema,
+    rateBreakdown: z.array(rateBreakdownEntrySchema)
+});
+//# sourceMappingURL=rated-usage.js.map

package/dist/billing/rating/schemas/rated-usage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rated-usage.js","sourceRoot":"","sources":["../../../../src/billing/rating/schemas/rated-usage.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,QAAQ,CAAC;AAC5B,OAAO,EAAE,eAAe,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAExE;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,UAAU,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC,CAAC;AAG1E;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,CAAC,MAAM,CAAC,oBAAoB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,WAAW,EAAE,CAAC,CAAC;AAS5F;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC7C,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC9B,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC1B,QAAQ,EAAE,kBAAkB;IAC5B,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC9B,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IACjC,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IACjC,aAAa,EAAE,mBAAmB;IAClC,SAAS,EAAE,CAAC,CAAC,KAAK,CAAC,eAAe,CAAC,CAAC,QAAQ,EAAE;CAC9C,CAAC,CAAC;AAIH;;;;GAIG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,CAAC,MAAM,CAAC;IAChD,IAAI,EAAE,oBAAoB;IAC1B,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,WAAW,EAAE;IAClC,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,WAAW,EAAE;IACpC,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,WAAW,EAAE;IACrC,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;CACzB,CAAC,CAAC;AAIH;;;GAGG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,CAAC,IAAI,CAAC;IACxC,OAAO;IACP,qBAAqB;IACrB,gBAAgB;IAChB,oBAAoB;IACpB,mBAAmB;CACnB,CAAC,CAAC;AAIH,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,WAAW,EAAE,QAAQ,CAAC,CAAC,CAAC;AAGzE,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC9C,cAAc,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,WAAW,EAAE;IACxC,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,WAAW,EAAE;IACtC,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IACjC,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAChC,UAAU,EAAE,gBAAgB;IAC5B,MAAM,EAAE,kBAAkB;IAC1B,QAAQ,EAAE,kBAAkB;IAC5B,aAAa,EAAE,CAAC,CAAC,KAAK,CAAC,wBAAwB,CAAC;CAChD,CAAC,CAAC"}

package/dist/billing/rating/schemas/rating-policy.d.ts

@@ -0,0 +1,86 @@
+import * as z from 'zod/v4';
+/**
+ * Per-feature override of base rating policy.
+ *
+ * `multiplier` is composed on top of any model-level multiplier (which
+ * itself sits on top of the base `1.0` — the SPEC keeps margin out of
+ * rating and inside the credit purchase price). Set this only when a
+ * feature has structurally different economics than its cost basis
+ * suggests (e.g. agent runs that incur queue overhead beyond raw token
+ * cost).
+ */
+export declare const featureRatingOverrideSchema: z.ZodObject<{
+    multiplier: z.ZodOptional<z.ZodNumber>;
+    minimumChargeCredits: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type FeatureRatingOverride = z.infer<typeof featureRatingOverrideSchema>;
+export declare const modelRatingOverrideSchema: z.ZodObject<{
+    multiplier: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type ModelRatingOverride = z.infer<typeof modelRatingOverrideSchema>;
+/**
+ * Safe heuristic floor used when no cost basis is known for an emitted
+ * unit (unknown model, new provider, or measurement-only path before a
+ * published price lands). The SPEC mandates this path must never produce
+ * a zero charge — that's how silent revenue holes happen.
+ *
+ * The heuristic floors target the median paid-tier provider cost for
+ * each unit class so we err on the side of slightly over-charging an
+ * unknown unit rather than serving free compute. `multiplier` is an
+ * additional safety factor on top of those floors.
+ */
+export declare const unknownCostHeuristicSchema: z.ZodObject<{
+    multiplier: z.ZodNumber;
+    floorUsdPerMillionInputTokens: z.ZodNumber;
+    floorUsdPerMillionOutputTokens: z.ZodNumber;
+    floorUsdPerImage: z.ZodNumber;
+    floorUsdPerAudioMinute: z.ZodNumber;
+    floorUsdPerRequest: z.ZodNumber;
+    floorUsdPerGbMonth: z.ZodNumber;
+    floorUsdPerGbEgress: z.ZodNumber;
+    floorUsdPerComputeSecond: z.ZodNumber;
+    floorUsdPerGpuSecond: z.ZodNumber;
+}, z.core.$strip>;
+export type UnknownCostHeuristic = z.infer<typeof unknownCostHeuristicSchema>;
+/**
+ * Rating policy — the deterministic recipe that converts a measured
+ * usage event into a charged credit count.
+ *
+ * Invariants (do not change without a SPEC update + ledger reconciler):
+ * - `creditValueUsd` is the **rating** value of a credit (cost-basis $).
+ *   The user-facing **purchase** price of a credit (cost-basis × margin)
+ *   lives in the credit-pack catalog, not here.
+ * - `roundUpToCredits` and `minimumChargeCredits` are positive and
+ *   typically equal (every chargeable op pays at least one round-up
+ *   bucket). They produce the small house-favoring rounding margin.
+ * - `pricingVersion` MUST be incremented on any change to base rates,
+ *   heuristic floors, or rounding policy so historical charges remain
+ *   reproducible from their ledger metadata.
+ */
+export declare const ratingPolicySchema: z.ZodObject<{
+    creditValueUsd: z.ZodNumber;
+    roundUpToCredits: z.ZodNumber;
+    minimumChargeCredits: z.ZodNumber;
+    unknownCostHeuristic: z.ZodObject<{
+        multiplier: z.ZodNumber;
+        floorUsdPerMillionInputTokens: z.ZodNumber;
+        floorUsdPerMillionOutputTokens: z.ZodNumber;
+        floorUsdPerImage: z.ZodNumber;
+        floorUsdPerAudioMinute: z.ZodNumber;
+        floorUsdPerRequest: z.ZodNumber;
+        floorUsdPerGbMonth: z.ZodNumber;
+        floorUsdPerGbEgress: z.ZodNumber;
+        floorUsdPerComputeSecond: z.ZodNumber;
+        floorUsdPerGpuSecond: z.ZodNumber;
+    }, z.core.$strip>;
+    featureOverrides: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        multiplier: z.ZodOptional<z.ZodNumber>;
+        minimumChargeCredits: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>>;
+    modelOverrides: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        multiplier: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>>;
+    pricingVersion: z.ZodString;
+}, z.core.$strip>;
+export type RatingPolicy = z.infer<typeof ratingPolicySchema>;
+//# sourceMappingURL=rating-policy.d.ts.map

package/dist/billing/rating/schemas/rating-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rating-policy.d.ts","sourceRoot":"","sources":["../../../../src/billing/rating/schemas/rating-policy.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,QAAQ,CAAC;AAE5B;;;;;;;;;GASG;AACH,eAAO,MAAM,2BAA2B;;;iBAGtC,CAAC;AAEH,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAC;AAEhF,eAAO,MAAM,yBAAyB;;iBAEpC,CAAC;AAEH,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAE5E;;;;;;;;;;GAUG;AACH,eAAO,MAAM,0BAA0B;;;;;;;;;;;iBAWrC,CAAC;AAEH,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAC;AAE9E;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;iBAQ7B,CAAC;AAEH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC"}