@usagekit/meter 0.7.0 → 0.9.0

package/dist/catalog.d.ts

@@ -1,10 +1,14 @@
-import type { ConnectionPolicy, MeterReserveInput, Operation, PricingCatalog, ReserveInput, ValidationFailure } from "@usagekit/core";
-/** Host lookup of a connection's provider, plan, manual prices and tracking policy. */
-export type ConnectionResolver = (connectionId: string) => Promise<ConnectionPolicy | undefined> | ConnectionPolicy | undefined;
-/** What reserve does with a request after the catalog and the connection policy spoke. */
-export type ReserveResolution = {
+import type { ConnectionPolicy, MeterReserveInput, MeterQuoteInput, Operation, PricingCatalog, ReserveInput, ValidationFailure } from "@usagekit/core";
+/** Host lookup of actual funding and pricing policy within the requested namespace. */
+export type ConnectionResolver = (scope: {
+    namespace: string;
+    connection: string;
+}) => Promise<ConnectionPolicy | undefined> | ConnectionPolicy | undefined;
+type EstimateResolution = {
     kind: "reserve";
-    input: ReserveInput;
+    input: Omit<ReserveInput, "operationId" | "reservationTtlMs" | "correlationId" | "parentOperationId">;
+    checkedAt?: string;
+    sampleSize?: number;
 } | {
     kind: "count";
     state: "passthrough" | "unpriced";
@@ -12,4 +16,15 @@ export type ReserveResolution = {
     kind: "invalid";
     failure: ValidationFailure;
 };
+export type ReserveResolution = Exclude<EstimateResolution, {
+    kind: "reserve";
+}> | {
+    kind: "reserve";
+    input: ReserveInput;
+};
+export declare function validateConnectionFunding(policy: ConnectionPolicy, fundingSource: ConnectionPolicy["fundingSource"], field?: string): ValidationFailure | null;
+/** Shared estimate resolution. No Store reads, writes, expiry maintenance or provider calls. */
+export declare function resolveEstimate(requested: MeterQuoteInput, catalog?: PricingCatalog, resolveConnection?: ConnectionResolver): Promise<EstimateResolution>;
+/** Replay retains the frozen estimate and provenance, even after funding or policy changes. */
 export declare function resolveReserve(requested: MeterReserveInput, existing: Operation | null, catalog?: PricingCatalog, resolveConnection?: ConnectionResolver): Promise<ReserveResolution>;
+export {};

package/dist/catalog.js

@@ -2,61 +2,116 @@ const invalid = (field, reason) => ({
     kind: "invalid",
     failure: { outcome: "invalid", field, reason },
 });
-/**
- * Order: a stored operation replays with its own estimate; then the connection's tracking
- * policy and free catalog operations count as passthrough; then a given estimate is used as is;
- * then the catalog resolves one (manual, measured, list, unknown), and an operation the catalog
- * does not know counts as unpriced.
- */
 const provenanceOf = (estimateSource, providerPriceVersion) => ({
     ...(estimateSource ? { estimateSource } : {}),
     ...(providerPriceVersion ? { providerPriceVersion } : {}),
 });
-export async function resolveReserve(requested, existing, catalog, resolveConnection) {
-    const { options = {}, estimate, estimateSource, providerPriceVersion, ...rest } = requested;
-    // A retry that omits the estimate replays the stored one, including provenance. A retry that
-    // sends an estimate keeps only the provenance on that request.
-    if (existing) {
-        if (estimate === undefined)
-            return {
-                kind: "reserve",
-                input: {
-                    ...rest,
-                    estimate: existing.estimate,
-                    ...provenanceOf(existing.estimateSource, existing.providerPriceVersion),
-                },
-            };
+export function validateConnectionFunding(policy, fundingSource, field = "fundingSource") {
+    if (policy.fundingSource !== "byok" && policy.fundingSource !== "platform")
         return {
-            kind: "reserve",
-            input: { ...rest, estimate, ...provenanceOf(estimateSource, providerPriceVersion) },
+            outcome: "invalid",
+            field: "fundingSource",
+            reason: "missing from the resolved connection policy",
         };
-    }
-    const policy = catalog && resolveConnection ? await resolveConnection(rest.scope.connection) : undefined;
+    if (policy.fundingSource !== fundingSource)
+        return { outcome: "invalid", field, reason: "differs from the connection funding source" };
+    return null;
+}
+/** Shared estimate resolution. No Store reads, writes, expiry maintenance or provider calls. */
+export async function resolveEstimate(requested, catalog, resolveConnection) {
+    const { options = {}, estimate, estimateSource, providerPriceVersion, ...rest } = requested;
+    const policy = await resolveConnection?.({
+        namespace: rest.scope.namespace,
+        connection: rest.scope.connection,
+    });
+    if (resolveConnection && !policy)
+        return invalid("estimate", "unknown connection");
     if (policy && policy.provider !== rest.provider)
         return invalid("provider", "differs from the connection provider");
+    if (policy) {
+        const failure = validateConnectionFunding(policy, rest.fundingSource);
+        if (failure)
+            return { kind: "invalid", failure };
+    }
     if (policy && catalog) {
         const known = catalog.operationsOf(policy.provider).find((o) => o.id === rest.operation);
-        if (policy.tracking?.[rest.operation] === "passthrough" || known?.billable === false)
+        if (known?.billable === false)
+            return { kind: "count", state: "passthrough" };
+        // Only catalog-declared nonbillable operations can omit platform customer pricing.
+        // Platform calls with a host estimate always reserve; only BYOK can opt out via tracking.
+        if (rest.fundingSource === "platform" && estimate === undefined)
+            return invalid("estimate", "required from host customer-price policy for platform funding");
+        if (rest.fundingSource === "byok" && policy.tracking?.[rest.operation] === "passthrough")
             return { kind: "count", state: "passthrough" };
         if (estimate === undefined) {
             if (!known)
                 return { kind: "count", state: "unpriced" };
-            const { tracking: _, ...connection } = policy, resolved = catalog.estimate({ ...connection, id: rest.scope.connection }, rest.operation, options);
-            return {
-                kind: "reserve",
-                input: {
-                    ...rest,
-                    estimate: resolved.quantities,
-                    estimateSource: resolved.source,
-                    ...(resolved.priceVersion ? { providerPriceVersion: resolved.priceVersion } : {}),
-                },
-            };
+            const { tracking: _, ...connection } = policy;
+            try {
+                const resolved = catalog.estimate({ ...connection, id: rest.scope.connection, fundingSource: rest.fundingSource }, rest.operation, options);
+                return {
+                    kind: "reserve",
+                    input: {
+                        ...rest,
+                        estimate: resolved.quantities,
+                        estimateSource: resolved.source,
+                        ...(resolved.priceVersion ? { providerPriceVersion: resolved.priceVersion } : {}),
+                    },
+                    ...(resolved.checkedAt ? { checkedAt: resolved.checkedAt } : {}),
+                    ...(resolved.sampleSize !== undefined ? { sampleSize: resolved.sampleSize } : {}),
+                };
+            }
+            catch (error) {
+                if (error instanceof Error && /^(InvalidInput|InvalidDecimal):/.test(error.message))
+                    return invalid("options", error.message);
+                throw error;
+            }
         }
     }
-    if (estimate === undefined)
+    if (estimate === undefined) {
         return invalid("estimate", catalog && resolveConnection ? "unknown connection" : "required without a catalog");
+    }
+    if (rest.fundingSource === "platform") {
+        if (!estimate.some((quantity) => quantity.unit !== "requests"))
+            return invalid("estimate", "platform funding requires a host customer price");
+        if (estimateSource === "manual" || estimateSource === "list" || estimateSource === "measured")
+            return invalid("estimateSource", "provider prices are BYOK-only");
+    }
     return {
         kind: "reserve",
-        input: { ...rest, estimate, ...provenanceOf(estimateSource, providerPriceVersion) },
+        input: {
+            ...rest,
+            estimate,
+            ...provenanceOf(estimateSource, providerPriceVersion),
+        },
+    };
+}
+/** Replay retains the frozen estimate and provenance, even after funding or policy changes. */
+export async function resolveReserve(requested, existing, catalog, resolveConnection) {
+    const { options: _, estimate, estimateSource, providerPriceVersion, ...rest } = requested;
+    if (existing)
+        return {
+            kind: "reserve",
+            input: {
+                ...rest,
+                estimate: estimate ?? existing.estimate,
+                ...(estimate === undefined
+                    ? provenanceOf(existing.estimateSource, existing.providerPriceVersion)
+                    : provenanceOf(estimateSource, providerPriceVersion)),
+            },
+        };
+    const { operationId, reservationTtlMs, correlationId, parentOperationId, ...quote } = requested;
+    const resolved = await resolveEstimate(quote, catalog, resolveConnection);
+    if (resolved.kind !== "reserve")
+        return resolved;
+    return {
+        ...resolved,
+        input: {
+            ...resolved.input,
+            operationId,
+            ...(reservationTtlMs !== undefined ? { reservationTtlMs: reservationTtlMs } : {}),
+            ...(correlationId !== undefined ? { correlationId: correlationId } : {}),
+            ...(parentOperationId !== undefined ? { parentOperationId: parentOperationId } : {}),
+        },
     };
 }

package/dist/meter.js

@@ -1,7 +1,7 @@
-import { resolveReserve } from "./catalog.js";
+import { resolveEstimate, resolveReserve } from "./catalog.js";
 import { InvalidInput } from "@usagekit/store";
 import { defaultPolicy } from "./policy.js";
-import { validate, reserveValidation, usageValidation, operationsValidation, sourceValidation, provenanceValidation, requestCountsValidation, } from "./validation.js";
+import { validate, quoteValidation, reserveValidation, usageValidation, operationsValidation, sourceValidation, provenanceValidation, requestCountsValidation, } from "./validation.js";
 import { canRead, canReadBudget, canReadShared, isShared } from "./access.js";
 import { defaultBudgetOrder, normalizeTags } from "@usagekit/core";
 import { validateBillingImportInput, validateBillingImportsQuery } from "@usagekit/store";
@@ -30,7 +30,86 @@ export function createMeter({ store, policy = defaultPolicy, clock, resolveOwner
         return invalid ? Promise.resolve(invalid) : safely(fn);
     };
     const read = async (fn) => safely(async () => ({ outcome: "ok", value: await fn() }));
-    return {
+    const meter = {
+        quote: async (access, requested) => {
+            const invalid = quoteValidation(requested);
+            if (invalid)
+                return invalid;
+            if (!access.canReadBillingDetail ||
+                !canRead(access, {
+                    kind: "principal",
+                    namespace: requested.scope.namespace,
+                    principal: requested.scope.principal,
+                }) ||
+                (requested.scope.group !== undefined &&
+                    !canRead(access, {
+                        kind: "group",
+                        namespace: requested.scope.namespace,
+                        group: requested.scope.group,
+                    })))
+                return { outcome: "forbidden" };
+            const owner = await resolveOwnership?.({
+                kind: "connection",
+                namespace: requested.scope.namespace,
+                connection: requested.scope.connection,
+            });
+            if (!owner ||
+                !canRead(access, owner) ||
+                (owner.kind === "principal"
+                    ? owner.principal !== requested.scope.principal
+                    : owner.group !== requested.scope.group))
+                return { outcome: "forbidden" };
+            if (requested.scope.accessCredential &&
+                !(await canReadBudget(resolveOwnership, access, {
+                    kind: "access_credential",
+                    namespace: requested.scope.namespace,
+                    accessCredential: requested.scope.accessCredential,
+                })))
+                return { outcome: "forbidden" };
+            return safely(async () => {
+                const resolved = await resolveEstimate(requested, catalog, resolveConnection);
+                if (resolved.kind === "invalid")
+                    return resolved.failure;
+                const quantities = resolved.kind === "reserve" ? resolved.input.estimate : [];
+                if (resolved.kind === "reserve") {
+                    const invalid = reserveValidation({ ...resolved.input, operationId: "quote" });
+                    if (invalid)
+                        return invalid;
+                }
+                const statuses = await meter.applicableBudgets(access, {
+                    scope: requested.scope,
+                    surface: requested.surface,
+                    source: requested.source,
+                    units: quantities.map((q) => q.unit),
+                    ...(requested.platformPools ? { platformPools: requested.platformPools } : {}),
+                });
+                if (statuses.outcome !== "ok")
+                    return statuses;
+                return {
+                    outcome: "ok",
+                    value: {
+                        quantities,
+                        ...(resolved.kind === "reserve"
+                            ? resolved.input.estimateSource
+                                ? { estimateSource: resolved.input.estimateSource }
+                                : {}
+                            : { estimateSource: "unknown" }),
+                        ...(resolved.kind === "reserve" && resolved.input.providerPriceVersion
+                            ? { providerPriceVersion: resolved.input.providerPriceVersion }
+                            : {}),
+                        ...(resolved.kind === "reserve" && resolved.checkedAt
+                            ? { checkedAt: resolved.checkedAt }
+                            : {}),
+                        ...(resolved.kind === "reserve" && resolved.sampleSize !== undefined
+                            ? { sampleSize: resolved.sampleSize }
+                            : {}),
+                        tracking: resolved.kind === "reserve" ? "metered" : resolved.state,
+                        budgets: statuses.value,
+                        asOf: clock.now().toISOString(),
+                    },
+                };
+            });
+        },
         importBilling: async (access, i) => {
             const invalid = validateBillingImportInput(i);
             if (invalid)
@@ -54,7 +133,10 @@ export function createMeter({ store, policy = defaultPolicy, clock, resolveOwner
                     : owner.group !== i.scope.group) ||
                 !canRead(access, owner))
                 return { outcome: "forbidden" };
-            const connection = await resolveConnection?.(i.scope.connection);
+            const connection = await resolveConnection?.({
+                namespace: i.scope.namespace,
+                connection: i.scope.connection,
+            });
             if (resolveConnection && (!connection || connection.provider !== i.provider))
                 return { outcome: "forbidden" };
             if (catalog && catalog.operationsOf(i.provider).length === 0)
@@ -246,4 +328,5 @@ export function createMeter({ store, policy = defaultPolicy, clock, resolveOwner
             });
         },
     };
+    return meter;
 }

package/dist/validation.d.ts

@@ -1,4 +1,4 @@
-import type { ValidationFailure, ReserveInput, UsageQuery, ApplicableBudgetsQuery, OperationsQuery, RequestCountsQuery } from "@usagekit/core";
+import type { MeterQuoteInput, ValidationFailure, ReserveInput, UsageQuery, ApplicableBudgetsQuery, OperationsQuery, RequestCountsQuery } from "@usagekit/core";
 export declare function validate(value: unknown, field?: string): ValidationFailure | null;
 /** The host sets both fields at authentication; a source outside its surface group is a forgery or a bug. */
 export declare function sourceValidation(i: Pick<ApplicableBudgetsQuery, "surface" | "source">): ValidationFailure | null;
@@ -10,3 +10,5 @@ export declare function provenanceValidation(i: {
     estimateSource?: string;
 }): ValidationFailure | null;
 export declare function requestCountsValidation(q: RequestCountsQuery): ValidationFailure | null;
+/** Validate the quote's required domain fields before touching policy or Store. */
+export declare function quoteValidation(i: MeterQuoteInput): ValidationFailure | null;

package/dist/validation.js

@@ -85,3 +85,39 @@ export function provenanceValidation(i) {
 export function requestCountsValidation(q) {
     return validate(q) ?? windowValidation(q);
 }
+/** Validate the quote's required domain fields before touching policy or Store. */
+export function quoteValidation(i) {
+    if (!i || typeof i !== "object" || !i.scope || typeof i.scope !== "object")
+        return { outcome: "invalid", field: "scope", reason: "required scope" };
+    for (const [field, value] of Object.entries({
+        namespace: i.scope.namespace,
+        principal: i.scope.principal,
+        connection: i.scope.connection,
+        costOwner: i.costOwner,
+        provider: i.provider,
+        operation: i.operation,
+    }))
+        if (typeof value !== "string" || !value.trim())
+            return { outcome: "invalid", field, reason: "required nonempty string" };
+    if (!["byok", "platform"].includes(i.fundingSource))
+        return { outcome: "invalid", field: "fundingSource", reason: "unknown funding source" };
+    if (!sourcesOf(i.surface)?.includes(i.source) || i.source === "import")
+        return { outcome: "invalid", field: "source", reason: "invalid quote source" };
+    if (i.estimate !== undefined && !Array.isArray(i.estimate))
+        return { outcome: "invalid", field: "estimate", reason: "expected quantities" };
+    if (i.estimate?.some((q) => !q ||
+        typeof q !== "object" ||
+        typeof q.unit !== "string" ||
+        !q.unit.trim() ||
+        typeof q.value !== "bigint" ||
+        !Number.isInteger(q.scale)))
+        return { outcome: "invalid", field: "estimate", reason: "expected exact quantities" };
+    if (i.options !== undefined &&
+        (typeof i.options !== "object" ||
+            i.options === null ||
+            Array.isArray(i.options) ||
+            Object.values(i.options).some((x) => typeof x !== "string")))
+        return { outcome: "invalid", field: "options", reason: "expected string options" };
+    return (reserveValidation({ ...i, operationId: "quote", estimate: i.estimate ?? [] }) ??
+        provenanceValidation(i));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usagekit/meter",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "type": "module",
   "license": "Apache-2.0",
   "description": "Admission, reservations, settlement and recovery.",
@@ -23,8 +23,8 @@
     "prepack": "node ../../scripts/package-license.mjs"
   },
   "dependencies": {
-    "@usagekit/core": "0.7.0",
-    "@usagekit/store": "0.7.0"
+    "@usagekit/core": "0.9.0",
+    "@usagekit/store": "0.9.0"
   },
   "sideEffects": false,
   "publishConfig": {
@@ -33,11 +33,11 @@
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/msniezynski/usagekit.git",
+    "url": "git+https://github.com/usagekit/usagekit.git",
     "directory": "packages/meter"
   },
   "homepage": "https://usagekit.dev",
   "bugs": {
-    "url": "https://github.com/msniezynski/usagekit/issues"
+    "url": "https://github.com/usagekit/usagekit/issues"
   }
 }