@usagekit/core 0.8.0 → 0.9.0

package/dist/contracts.d.ts

@@ -269,8 +269,8 @@ export type ReserveResult = ValidationFailure | {
     operation: Operation;
 }
 /**
- * The connection's tracking policy is passthrough for this operation, or the catalog marks it
- * free: counted with state passthrough, never reserved. The caller may forward the call.
+ * The BYOK connection's tracking policy is passthrough for this operation, or the catalog
+ * marks it free: counted with state passthrough, never reserved. The caller may forward the call.
  */
  | {
     outcome: "passthrough";
@@ -289,15 +289,30 @@ export type ReserveResult = ValidationFailure | {
 /** Where a reserve estimate came from, in resolution order. */
 export type EstimateSource = "manual" | "measured" | "list" | "unknown";
 /**
- * Meter reserve input. With a catalog, estimate may be omitted: the Meter resolves it from the
- * catalog for the connection and the request options. Store always receives a ReserveInput.
+ * Meter reserve input. For BYOK with a catalog, estimate may be omitted: the Meter resolves it
+ * for the connection and request options. Billable platform-funded calls require a host
+ * customer-price estimate; catalog-declared nonbillable calls are counted without a reservation.
+ * Store reservations always receive a ReserveInput.
  */
 export type MeterReserveInput = Omit<ReserveInput, "estimate"> & {
-    /** Omitted: the Meter resolves it through its catalog and the connection policy. */
+    /** BYOK may omit for catalog resolution; billable platform calls require host customer pricing. */
     estimate?: readonly Quantity[];
     /** Request options that move the price, read from the request by the descriptor. */
     options?: Readonly<Record<string, string>>;
 };
+/** Authorized advisory estimate. No operation identity or accounting side effects. */
+export type MeterQuoteInput = Omit<MeterReserveInput, "operationId" | "reservationTtlMs" | "correlationId" | "parentOperationId">;
+export type MeterQuote = {
+    quantities: readonly Quantity[];
+    /** Matches stored reservation provenance; omitted when none was supplied or resolved. */
+    estimateSource?: EstimateSource;
+    providerPriceVersion?: string;
+    checkedAt?: string;
+    sampleSize?: number;
+    tracking: "metered" | "passthrough" | "unpriced";
+    budgets: readonly BudgetStatus[];
+    asOf: string;
+};
 /**
  * Non-operation outcomes, counted per state and never reserved. Metered requests are the
  * operations themselves and are not counted here.
@@ -636,6 +651,7 @@ export type ExpireReservationsResult = ValidationFailure | {
  * Admission sweeps at most one default batch. Maintenance owns the remaining expired backlog.
  */
 export interface Meter {
+    quote(access: AccessContext, input: MeterQuoteInput): Promise<ReadResult<MeterQuote>>;
     importBilling(access: AccessContext, input: BillingImportInput): Promise<BillingImportResult | {
         outcome: "forbidden";
     }>;

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export type { Money, Quantity, AccessCredential, Scope, FundingSource, Surface, Source, BudgetWindow, BudgetScope, Budget, BudgetAlert, BudgetAlertCrossed, LifecycleState, Certainty, Measurement, Cost, Receipt, ReserveInput, ReserveResult, Operation, OperationRef, OperationCommand, Lease, DispatchGrant, DispatchIntentInput, LeaseRenewalInput, LeaseRenewal, RecoveryClaimInput, RecoveryClaim, Authority, SettleInput, ReleaseInput, CorrectionInput, SettleResult, ReleaseResult, UsageScope, AccessContext, UsageQuery, UsageRow, UsagePage, OperationsQuery, OperationsPage, DefinedBudgetsQuery, ApplicableBudgetsQuery, BudgetStatus, ReadResult, AllowanceExceeded, Meter, MeterReserveInput, EstimateSource, RequestState, CountRequestInput, CountRequestResult, RequestCountsQuery, RequestCountRow, RequestCountsPage, } from "./contracts.js";
+export type { Money, Quantity, AccessCredential, Scope, FundingSource, Surface, Source, BudgetWindow, BudgetScope, Budget, BudgetAlert, BudgetAlertCrossed, LifecycleState, Certainty, Measurement, Cost, Receipt, ReserveInput, ReserveResult, Operation, OperationRef, OperationCommand, Lease, DispatchGrant, DispatchIntentInput, LeaseRenewalInput, LeaseRenewal, RecoveryClaimInput, RecoveryClaim, Authority, SettleInput, ReleaseInput, CorrectionInput, SettleResult, ReleaseResult, UsageScope, AccessContext, UsageQuery, UsageRow, UsagePage, OperationsQuery, OperationsPage, DefinedBudgetsQuery, ApplicableBudgetsQuery, BudgetStatus, ReadResult, AllowanceExceeded, Meter, MeterReserveInput, MeterQuoteInput, MeterQuote, EstimateSource, RequestState, CountRequestInput, CountRequestResult, RequestCountsQuery, RequestCountRow, RequestCountsPage, } from "./contracts.js";
 export { requestStates } from "./policy.js";
 export { resolveWindow } from "./windows.js";
 export type { ResolvedWindow } from "./windows.js";
@@ -8,6 +8,6 @@ export type { ValidationFailure, AdmissionPolicy, BudgetOwner } from "./contract
 export { defaultBudgetOrder, sourcesOf, surfaceMatches, tagPattern, normalizeTags, } from "./policy.js";
 export type { ExpireReservationsInput, ExpireReservationsResult } from "./contracts.js";
 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 { ProviderId, OperationId, ProviderAuth, BillingUnit, ProviderPlan, PriceRow, PriceBasis, PriceCalculation, RequestMatch, ProviderOperation, BalanceProbe, PriceListSource, BillingExport, ProviderDescriptor, BalanceSnapshot, BillingLine, DescriptorProblem, PricingCatalog, ConnectionPolicy, TrackingPolicy, MeasuredPrice, } from "./providers.js";
+export { validateDescriptor, validateConnectionPolicy } from "./providers.js";
 export type { ImportAttribution, BillingImportInput, ReconciliationEntry, BillingImportRecord, BillingImportResult, BillingImportsQuery, BillingImportsPage, BillingOperationChange, } from "./billing.js";

package/dist/index.js

@@ -4,4 +4,4 @@ export { fromDecimalString, toDecimalString, formatMoney, add as addMoney, sub a
 export { normalizeScale, add as addQuantity, compare as compareQuantity, format as formatQuantity, } from "./quantity.js";
 export { defaultBudgetOrder, sourcesOf, surfaceMatches, tagPattern, normalizeTags, } from "./policy.js";
 export { decodeMeterJson } from "./wire.js";
-export { validateDescriptor } from "./providers.js";
+export { validateDescriptor, validateConnectionPolicy } from "./providers.js";

package/dist/providers.d.ts

@@ -1,4 +1,4 @@
-import type { EstimateSource, Money, Quantity } from "./contracts.js";
+import type { EstimateSource, FundingSource, Money, Quantity, ValidationFailure } from "./contracts.js";
 /**
  * Provider descriptors: data that tells usagekit how to price, route, meter and reconcile one
  * provider. Descriptors live in `@usagekit/providers`; the core contract does not depend on
@@ -36,11 +36,41 @@ export type ProviderPlan = {
         value: bigint;
     };
     allowanceMode: "hard" | "soft";
+    /** Provider subscription data; never a per-receipt debit. */
+    subscription?: {
+        period: "month";
+        fee: Money;
+        source: string;
+        checkedAt: string;
+    };
 };
 /**
- * One list price. The descriptor never holds negotiated prices, discounts or volume tiers beyond
- * the public list; those are manual prices on the connection.
+ * Overrides default to a whole-call price; item overrides replace a formula coefficient.
  */
+export type PriceBasis = "call" | "item";
+export type PriceCalculation = {
+    kind: "option_multiplier";
+    multiplierOption: {
+        key: string;
+        value: string;
+        factor: string;
+    };
+} | {
+    kind: "additional_pages";
+    depthOption: string;
+    pageSize: number;
+    additionalPageFactor: string;
+} | {
+    kind: "base_plus_items";
+    itemCountOption: string;
+    perItem: string;
+    multiplierOption?: {
+        key: string;
+        value: string;
+        factor: string;
+    };
+};
+/** One public list price, with optional request calculation metadata. */
 export type PriceRow = {
     /** ISO date. */
     validFrom: string;
@@ -54,6 +84,7 @@ export type PriceRow = {
     unit: BillingUnit;
     /** Exact nonnegative decimal in that unit. */
     perUnit: string;
+    calculation?: PriceCalculation;
     /** URL of the public price source. */
     source: string;
     /** ISO date of the last check against the source. */
@@ -76,6 +107,19 @@ export type ProviderOperation = {
     match: readonly RequestMatch[];
     /** Options that move the price; values are extracted from the request by `options`. */
     optionKeys?: readonly string[];
+    /** Exhaustive documented request fields; unclassified fields cannot be safely priced. */
+    requestPricing?: {
+        source: string;
+        formula: string;
+        priceFields: Readonly<Record<string, {
+            formula: string;
+            /** A supplied opaque value can prevent any defensible upper bound. */
+            unpricedWhen?: "present" | "true";
+            /** Documented item count when this field is omitted. */
+            defaultCount?: number;
+        }>>;
+        neutralFields: readonly string[];
+    };
     /**
      * Cost is known from the response body, only after a later call, or never per call.
      * response: settle on stream close. deferred: settle with unknown cost, keep pending, resolve
@@ -132,6 +176,8 @@ export type ProviderDescriptor = {
     /** Origin and optional base path, for example "https://api.example.com". */
     upstream: string;
     auth: ProviderAuth;
+    /** Pricing and matching see body/query only when declared; method and URL path are always available. */
+    pricingInputs: readonly ("body" | "query")[];
     stripRequestHeaders?: readonly string[];
     billing: {
         unit: BillingUnit;
@@ -176,26 +222,39 @@ export type BillingLine = {
         to: string;
     };
 };
-/** Per-connection choice per catalog operation; the default is metered. */
+/** Per-operation tracking; passthrough opts BYOK out of spend enforcement only. */
 export type TrackingPolicy = "metered" | "passthrough";
 /** Median of a connection's settled receipts for one operation, with its sample size. */
 export type MeasuredPrice = (operation: OperationId) => {
     quantity: Quantity;
     samples: number;
+    basis?: PriceBasis;
+    checkedAt?: string;
 } | undefined;
 /**
- * Connection data a host resolves for the Meter: provider, selected plan, manual per-call prices,
+ * Connection data a host resolves for the Meter: provider, selected plan, BYOK manual prices,
  * measured prices and tracking policy, all keyed by OperationId. overage is true when the host
  * knows the plan allowance is exhausted.
  */
 export type ConnectionPolicy = {
     provider: ProviderId;
+    /** Actual connection funding, derived by the host from trusted server state. */
+    fundingSource: FundingSource;
     plan?: string;
+    /** BYOK only: estimates the user's own provider cost, including genuine zero. */
     manualPrices?: Readonly<Record<OperationId, Quantity>>;
+    manualPriceBasis?: Readonly<Record<OperationId, PriceBasis>>;
     measured?: MeasuredPrice;
     tracking?: Readonly<Record<OperationId, TrackingPolicy>>;
     overage?: boolean;
 };
+/** Validate raw connection settings before saving. Manual prices are BYOK-only. */
+export declare function validateConnectionPolicy(policy: {
+    fundingSource: FundingSource;
+    tracking?: unknown;
+    manualPrices?: unknown;
+    manualPriceBasis?: unknown;
+}, operations: readonly Pick<ProviderOperation, "id" | "billable">[]): ValidationFailure | null;
 /**
  * What the Meter needs from a provider catalog. `@usagekit/providers` createCatalog satisfies
  * it; the Meter does not depend on that package. operationsOf lists the operations of an
@@ -208,10 +267,17 @@ export type PricingCatalog = {
         quantities: Quantity[];
         source: EstimateSource;
         priceVersion?: string;
+        checkedAt?: string;
+        sampleSize?: number;
     };
     operationsOf(providerId: ProviderId): readonly ProviderOperation[];
 };
 export type DescriptorProblem = {
+    kind: "invalid_pricing_inputs";
+} | {
+    kind: "undeclared_query_input";
+    operation: OperationId;
+} | {
     kind: "duplicate_operation";
     operation: OperationId;
 } | {
@@ -236,6 +302,14 @@ export type DescriptorProblem = {
     kind: "invalid_price";
     row: number;
     field: "perUnit" | "validFrom" | "checkedAt" | "source";
+} | {
+    kind: "invalid_calculation";
+    row: number;
+    field: string;
+} | {
+    kind: "invalid_subscription";
+    plan: string;
+    field: string;
 } | {
     kind: "unknown_probe_operation";
     operation: OperationId;

package/dist/providers.js

@@ -1,3 +1,37 @@
+/** Validate raw connection settings before saving. Manual prices are BYOK-only. */
+export function validateConnectionPolicy(policy, operations) {
+    const invalid = (field, reason) => ({
+        outcome: "invalid",
+        field,
+        reason,
+    });
+    if (policy.fundingSource === "platform") {
+        for (const field of ["manualPrices", "manualPriceBasis"]) {
+            const value = policy[field];
+            const absent = value == null ||
+                (typeof value === "object" && !Array.isArray(value) && Object.keys(value).length === 0);
+            if (!absent)
+                return invalid(field, "manual provider prices are BYOK-only");
+        }
+    }
+    const { tracking } = policy;
+    if (tracking === undefined)
+        return null;
+    if (!tracking || typeof tracking !== "object" || Array.isArray(tracking))
+        return invalid("tracking", "must be an operation-to-tracking map");
+    for (const [id, mode] of Object.entries(tracking)) {
+        const operation = operations.find((entry) => entry.id === id);
+        if (policy.fundingSource === "platform" &&
+            operation?.billable !== false &&
+            (mode === "passthrough" || mode === "unpriced"))
+            return invalid(`tracking.${id}`, "billable platform operations must be metered; credits charges cannot be opted out");
+        if (!operation)
+            return invalid(`tracking.${id}`, "unknown operation");
+        if (mode !== "metered" && mode !== "passthrough")
+            return invalid(`tracking.${id}`, "must be metered or passthrough");
+    }
+    return null;
+}
 const isoDate = (text) => /^\d{4}-\d{2}-\d{2}/.test(text) && Number.isFinite(Date.parse(text));
 /**
  * Structural problems of a descriptor, in a stable order: operations, plans, prices, probe,
@@ -5,8 +39,15 @@ const isoDate = (text) => /^\d{4}-\d{2}-\d{2}/.test(text) && Number.isFinite(Dat
  */
 export function validateDescriptor(d) {
     const problems = [];
+    if (!Array.isArray(d.pricingInputs) ||
+        d.pricingInputs.some((part) => part !== "body" && part !== "query") ||
+        new Set(d.pricingInputs).size !== d.pricingInputs.length)
+        problems.push({ kind: "invalid_pricing_inputs" });
     const operations = new Map();
     for (const op of d.operations) {
+        if (!(Array.isArray(d.pricingInputs) && d.pricingInputs.includes("query")) &&
+            op.match.some((rule) => Object.keys(rule.query ?? {}).length > 0))
+            problems.push({ kind: "undeclared_query_input", operation: op.id });
         if (operations.has(op.id))
             problems.push({ kind: "duplicate_operation", operation: op.id });
         else
@@ -20,6 +61,17 @@ export function validateDescriptor(d) {
         if (plans.has(plan.id))
             problems.push({ kind: "duplicate_plan", plan: plan.id });
         plans.add(plan.id);
+        const fee = plan.subscription;
+        if (fee) {
+            for (const [field, valid] of Object.entries({
+                period: fee.period === "month",
+                fee: fee.fee.currency === "USD" && typeof fee.fee.units === "bigint" && fee.fee.units >= 0n,
+                source: Boolean(fee.source.trim()),
+                checkedAt: isoDate(fee.checkedAt),
+            }))
+                if (!valid)
+                    problems.push({ kind: "invalid_subscription", plan: plan.id, field });
+        }
     }
     d.prices.forEach((row, index) => {
         const op = operations.get(row.operation);
@@ -30,8 +82,37 @@ export function validateDescriptor(d) {
         for (const key of Object.keys(row.option ?? {}))
             if (op && !(op.optionKeys ?? []).includes(key))
                 problems.push({ kind: "unknown_price_option", row: index, option: key });
-        if (!/^\d+(\.\d+)?$/.test(row.perUnit))
+        if (!/^\d+(\.\d{1,18})?$/.test(row.perUnit))
             problems.push({ kind: "invalid_price", row: index, field: "perUnit" });
+        const c = row.calculation;
+        if (c) {
+            const decimal = (x) => /^\d+(\.\d{1,18})?$/.test(x);
+            const option = (key) => {
+                if (op && !(op.optionKeys ?? []).includes(key))
+                    problems.push({ kind: "unknown_price_option", row: index, option: key });
+            };
+            if (c.kind === "additional_pages") {
+                option(c.depthOption);
+                if (!Number.isSafeInteger(c.pageSize) || c.pageSize < 1)
+                    problems.push({ kind: "invalid_calculation", row: index, field: "pageSize" });
+                if (!decimal(c.additionalPageFactor))
+                    problems.push({ kind: "invalid_calculation", row: index, field: "additionalPageFactor" });
+            }
+            else if (c.kind === "base_plus_items") {
+                option(c.itemCountOption);
+                if (!decimal(c.perItem))
+                    problems.push({ kind: "invalid_calculation", row: index, field: "perItem" });
+            }
+            else if (c.kind !== "option_multiplier")
+                problems.push({ kind: "invalid_calculation", row: index, field: "kind" });
+            if (c.kind === "option_multiplier" && !c.multiplierOption)
+                problems.push({ kind: "invalid_calculation", row: index, field: "multiplierOption" });
+            if ((c.kind === "base_plus_items" || c.kind === "option_multiplier") && c.multiplierOption) {
+                option(c.multiplierOption.key);
+                if (!c.multiplierOption.value.trim() || !decimal(c.multiplierOption.factor))
+                    problems.push({ kind: "invalid_calculation", row: index, field: "multiplierOption" });
+            }
+        }
         if (!isoDate(row.validFrom))
             problems.push({ kind: "invalid_price", row: index, field: "validFrom" });
         if (!isoDate(row.checkedAt))

package/package.json

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