@usagekit/core 0.4.0 → 0.5.0

package/dist/billing.d.ts

@@ -0,0 +1,97 @@
+import type { BudgetAlertCrossed, Cost, FundingSource, Money, Operation, Receipt, Scope, ValidationFailure } from "./contracts.js";
+import type { BillingLine } from "./providers.js";
+/** Trusted historical attribution for calls the application did not observe. */
+export type ImportAttribution = {
+    fundingSource: FundingSource;
+    costOwner: string;
+    creditAccountRef?: string;
+    customerPriceVersion?: string;
+    providerPriceVersion?: string;
+    platformPools?: readonly string[];
+};
+/** A complete export for one connection and half-open window. Never grants dispatch. */
+export type BillingImportInput = {
+    scope: Scope;
+    provider: string;
+    /** Lower-case SHA-256 of the original file, computed before the atomic command. */
+    fileHash: string;
+    window: {
+        from: string;
+        to: string;
+    };
+    /** null for the first import; the current import id for a revision. Prevents lost updates. */
+    expectedPreviousImportId: string | null;
+    attribution: ImportAttribution;
+    lines: readonly BillingLine[];
+};
+/** Exact comparison. Unknown ledger cost remains unknown; signed differences are never prorated. */
+export type ReconciliationEntry = {
+    id: string;
+    importId: string;
+    scope: Scope;
+    provider: string;
+    /** Present for operation-specific aggregate evidence. */
+    operation?: string;
+    window: {
+        from: string;
+        to: string;
+    };
+    kind: "aggregate" | "import_total";
+    ledgerTotal: Cost;
+    evidenceTotal: Money;
+    /** evidenceTotal - ledgerTotal, or null when any observed cost is unknown. */
+    differenceUnits: bigint | null;
+    unknownOperations: bigint;
+    evidenceRef: string;
+};
+export type BillingImportRecord = {
+    id: string;
+    scope: Scope;
+    provider: string;
+    fileHash: string;
+    window: {
+        from: string;
+        to: string;
+    };
+    recordedAt: string;
+    supersedes?: string;
+    /** Projected from the import family pointer; earlier evidence remains available. */
+    supersededBy?: string;
+    matchedOperationIds: readonly string[];
+    unobservedOperationIds: readonly string[];
+    reconciliations: readonly ReconciliationEntry[];
+    alerts: readonly BudgetAlertCrossed[];
+};
+export type BillingImportResult = ValidationFailure | {
+    outcome: "imported";
+    replayed: boolean;
+    record: BillingImportRecord;
+} | {
+    outcome: "rejected";
+    reason: "previous_import_conflict" | "payload_conflict" | "ambiguous_request" | "active_operation" | "operation_state" | "evidence_conflict";
+    latestImportId: string | null;
+    line?: number;
+};
+export type BillingImportsQuery = {
+    scope: {
+        namespace: string;
+        principal: string;
+    };
+    connection: string;
+    from: string;
+    to: string;
+    /** Include superseded import evidence; defaults to false. */
+    history?: boolean;
+    limit?: number;
+};
+export type BillingImportsPage = {
+    records: readonly BillingImportRecord[];
+    asOf: string;
+    truncated: boolean;
+};
+/** Atomic adapter changes prepared against its transaction's operation snapshot. */
+export type BillingOperationChange = {
+    before: Operation | null;
+    after: Operation;
+    receipt: Receipt;
+};

package/dist/billing.js

@@ -0,0 +1 @@
+export {};

package/dist/contracts.d.ts

@@ -1,3 +1,4 @@
+import type { BillingImportInput, BillingImportResult, BillingImportsQuery, BillingImportsPage } from "./billing.js";
 export type ValidationFailure = {
     outcome: "invalid";
     field: string;
@@ -46,7 +47,7 @@ export type Scope = {
 };
 export type FundingSource = "byok" | "platform";
 export type Surface = "app" | "programmatic";
-export type Source = "app" | "worker" | "api" | "sdk" | "cli" | "mcp" | "proxy";
+export type Source = "app" | "worker" | "api" | "sdk" | "cli" | "mcp" | "proxy" | "import";
 /** Timestamps are UTC ISO strings. Resolved reservation epochs remain immutable. */
 export type BudgetWindow = {
     kind: "calendar_month";
@@ -163,6 +164,8 @@ export type Cost = {
  */
 export type Receipt = {
     id: string;
+    /** Existing receipts without this field are dispatch evidence. */
+    source?: "dispatch" | "probe" | "import";
     supersedes?: string;
     measurements: readonly Measurement[];
     cost: Cost;
@@ -514,6 +517,8 @@ export type AccessContext = {
     readablePools: readonly string[] | "*";
     canReadBillingDetail: boolean;
     canManageBudgets: boolean;
+    /** Explicit billing write permission. Read access or budget management does not imply it. */
+    canImportBilling?: boolean;
 };
 /**
  * groupBy: "principal" is allowed only for group or namespace scope.
@@ -631,6 +636,10 @@ export type ExpireReservationsResult = ValidationFailure | {
  * Admission sweeps at most one default batch. Maintenance owns the remaining expired backlog.
  */
 export interface Meter {
+    importBilling(access: AccessContext, input: BillingImportInput): Promise<BillingImportResult | {
+        outcome: "forbidden";
+    }>;
+    billingImports(access: AccessContext, query: BillingImportsQuery): Promise<ReadResult<BillingImportsPage>>;
     expireReservations(input: ExpireReservationsInput): Promise<ExpireReservationsResult>;
     reserve(input: MeterReserveInput): Promise<ReserveResult>;
     countRequest(input: CountRequestInput): Promise<CountRequestResult>;

package/dist/index.d.ts

@@ -10,3 +10,4 @@ export type { ExpireReservationsInput, ExpireReservationsResult } from "./contra
 export { decodeMeterJson } from "./wire.js";
 export type { ProviderId, OperationId, ProviderAuth, BillingUnit, ProviderPlan, PriceRow, RequestMatch, ProviderOperation, BalanceProbe, PriceListSource, BillingExport, ProviderDescriptor, BalanceSnapshot, BillingLine, DescriptorProblem, PricingCatalog, ConnectionPolicy, TrackingPolicy, MeasuredPrice, } from "./providers.js";
 export { validateDescriptor } from "./providers.js";
+export type { ImportAttribution, BillingImportInput, ReconciliationEntry, BillingImportRecord, BillingImportResult, BillingImportsQuery, BillingImportsPage, BillingOperationChange, } from "./billing.js";

package/dist/policy.js

@@ -19,7 +19,7 @@ export function normalizeTags(tags) {
 }
 const surfaceSources = Object.freeze({
     app: Object.freeze(["app", "worker"]),
-    programmatic: Object.freeze(["api", "sdk", "cli", "mcp", "proxy"]),
+    programmatic: Object.freeze(["api", "sdk", "cli", "mcp", "proxy", "import"]),
 });
 /** Sources a surface budget covers. Every Source belongs to exactly one Surface. */
 export const sourcesOf = (surface) => surfaceSources[surface];

package/dist/wire.js

@@ -29,6 +29,20 @@ export function decodeMeterJson(text) {
             ["passthrough", "unpriced", "cached", "rate_limited"].includes(String(v.state)) &&
             decimal(v.count))
             return { ...v, count: BigInt(v.count) };
+        if (typeof v.id === "string" &&
+            typeof v.importId === "string" &&
+            ["aggregate", "import_total"].includes(String(v.kind)) &&
+            v.scope &&
+            v.window &&
+            v.ledgerTotal &&
+            v.evidenceTotal &&
+            decimal(v.unknownOperations) &&
+            (v.differenceUnits === null || decimal(v.differenceUnits)))
+            return {
+                ...v,
+                unknownOperations: BigInt(v.unknownOperations),
+                differenceUnits: v.differenceUnits === null ? null : BigInt(v.differenceUnits),
+            };
         return value;
     });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usagekit/core",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "type": "module",
   "license": "Apache-2.0",
   "description": "Exact quantities, ownership and pure domain types.",