@usagekit/meter 0.3.0 → 0.5.0

package/dist/catalog.d.ts

@@ -0,0 +1,15 @@
+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 = {
+    kind: "reserve";
+    input: ReserveInput;
+} | {
+    kind: "count";
+    state: "passthrough" | "unpriced";
+} | {
+    kind: "invalid";
+    failure: ValidationFailure;
+};
+export declare function resolveReserve(requested: MeterReserveInput, existing: Operation | null, catalog?: PricingCatalog, resolveConnection?: ConnectionResolver): Promise<ReserveResolution>;

package/dist/catalog.js

@@ -0,0 +1,62 @@
+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),
+                },
+            };
+        return {
+            kind: "reserve",
+            input: { ...rest, estimate, ...provenanceOf(estimateSource, providerPriceVersion) },
+        };
+    }
+    const policy = catalog && resolveConnection ? await resolveConnection(rest.scope.connection) : undefined;
+    if (policy && policy.provider !== rest.provider)
+        return invalid("provider", "differs from the connection provider");
+    if (policy && catalog) {
+        const known = catalog.operationsOf(policy.provider).find((o) => o.id === rest.operation);
+        if (policy.tracking?.[rest.operation] === "passthrough" || known?.billable === false)
+            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 } : {}),
+                },
+            };
+        }
+    }
+    if (estimate === undefined)
+        return invalid("estimate", catalog && resolveConnection ? "unknown connection" : "required without a catalog");
+    return {
+        kind: "reserve",
+        input: { ...rest, estimate, ...provenanceOf(estimateSource, providerPriceVersion) },
+    };
+}

package/dist/index.d.ts

@@ -3,3 +3,5 @@ export { createMeter } from "./meter.js";
 export { defaultPolicy } from "./policy.js";
 export type { MeterPolicy } from "./policy.js";
 export type { OwnershipResolver } from "./access.js";
+export { resolveReserve } from "./catalog.js";
+export type { ConnectionResolver, ReserveResolution } from "./catalog.js";

package/dist/index.js

@@ -1,2 +1,3 @@
 export { createMeter } from "./meter.js";
 export { defaultPolicy } from "./policy.js";
+export { resolveReserve } from "./catalog.js";

package/dist/meter.d.ts

@@ -1,9 +1,13 @@
-import type { Meter } from "@usagekit/core";
+import type { Meter, PricingCatalog } from "@usagekit/core";
+import type { ConnectionResolver } from "./catalog.js";
 import type { Store, Clock } from "@usagekit/store";
 import type { MeterPolicy } from "./policy.js";
-export declare function createMeter({ store, policy, clock, resolveOwnership, }: {
+export declare function createMeter({ store, policy, clock, resolveOwnership, catalog, resolveConnection, }: {
     store: Store;
     policy?: MeterPolicy;
     clock: Clock;
     resolveOwnership?: import("./access.js").OwnershipResolver;
+    /** With resolveConnection, lets reserve omit estimate and applies tracking policy. */
+    catalog?: PricingCatalog;
+    resolveConnection?: ConnectionResolver;
 }): Meter;

package/dist/meter.js

@@ -1,9 +1,11 @@
+import { resolveReserve } from "./catalog.js";
 import { InvalidInput } from "@usagekit/store";
 import { defaultPolicy } from "./policy.js";
-import { validate, reserveValidation, usageValidation, operationsValidation, sourceValidation, } from "./validation.js";
+import { validate, reserveValidation, usageValidation, operationsValidation, sourceValidation, provenanceValidation, requestCountsValidation, } from "./validation.js";
 import { canRead, canReadBudget, canReadShared, isShared } from "./access.js";
 import { defaultBudgetOrder, normalizeTags } from "@usagekit/core";
-export function createMeter({ store, policy = defaultPolicy, clock, resolveOwnership, }) {
+import { validateBillingImportInput, validateBillingImportsQuery } from "@usagekit/store";
+export function createMeter({ store, policy = defaultPolicy, clock, resolveOwnership, catalog, resolveConnection, }) {
     if (!Number.isFinite(clock.now().getTime()))
         throw new Error("InvalidInput: clock");
     if (policy.budgetOrder.length !== defaultBudgetOrder.length ||
@@ -29,19 +31,99 @@ export function createMeter({ store, policy = defaultPolicy, clock, resolveOwner
     };
     const read = async (fn) => safely(async () => ({ outcome: "ok", value: await fn() }));
     return {
-        expireReservations: (i) => command(i, () => store.expireReservations(i)),
-        reserve: async (raw) => {
-            const invalid = reserveValidation(raw);
+        importBilling: async (access, i) => {
+            const invalid = validateBillingImportInput(i);
             if (invalid)
                 return invalid;
-            // Tags are attribution: sorted here so every adapter stores one canonical order.
-            const tags = raw.scope.tags === undefined ? undefined : normalizeTags(raw.scope.tags), i = tags ? { ...raw, scope: { ...raw.scope, tags } } : raw;
-            return safely(async () => {
-                const existing = await store.getOperation({
+            if (access.canImportBilling !== true ||
+                !access.canReadBillingDetail ||
+                !canRead(access, {
+                    kind: "principal",
                     namespace: i.scope.namespace,
                     principal: i.scope.principal,
-                    operationId: i.operationId,
+                }))
+                return { outcome: "forbidden" };
+            const owner = await resolveOwnership?.({
+                kind: "connection",
+                namespace: i.scope.namespace,
+                connection: i.scope.connection,
+            });
+            if (!owner ||
+                (owner.kind === "principal"
+                    ? owner.principal !== i.scope.principal
+                    : owner.group !== i.scope.group) ||
+                !canRead(access, owner))
+                return { outcome: "forbidden" };
+            const connection = await resolveConnection?.(i.scope.connection);
+            if (resolveConnection && (!connection || connection.provider !== i.provider))
+                return { outcome: "forbidden" };
+            if (catalog && catalog.operationsOf(i.provider).length === 0)
+                return { outcome: "forbidden" };
+            return safely(() => store.importBilling(i));
+        },
+        billingImports: async (access, q) => {
+            const invalid = validateBillingImportsQuery(q);
+            if (invalid)
+                return invalid;
+            if (!access.canReadBillingDetail ||
+                !canRead(access, { kind: "principal", ...q.scope }) ||
+                !(await canReadBudget(resolveOwnership, access, {
+                    kind: "connection",
+                    namespace: q.scope.namespace,
+                    connection: q.connection,
+                })))
+                return { outcome: "forbidden" };
+            return read(() => store.billingImports(q));
+        },
+        expireReservations: (i) => command(i, () => store.expireReservations(i)),
+        reserve: async (requested) => {
+            if (requested.source === "import")
+                return {
+                    outcome: "invalid",
+                    field: "source",
+                    reason: "import source is reserved for authorized billing evidence",
+                };
+            const early = validate({ ...requested, estimate: requested.estimate ?? [] }) ??
+                sourceValidation(requested) ??
+                provenanceValidation(requested);
+            if (early)
+                return early;
+            return safely(async () => {
+                const existing = await store.getOperation({
+                    namespace: requested.scope.namespace,
+                    principal: requested.scope.principal,
+                    operationId: requested.operationId,
                 });
+                const resolution = await resolveReserve(requested, existing, catalog, resolveConnection);
+                if (resolution.kind === "invalid")
+                    return resolution.failure;
+                if (resolution.kind === "count") {
+                    const { scope, surface, source, provider, operation, platformPools } = requested;
+                    const counted = await store.countRequest({
+                        commandId: requested.operationId,
+                        scope,
+                        surface,
+                        source,
+                        provider,
+                        operation,
+                        state: resolution.state,
+                        ...(platformPools ? { platformPools } : {}),
+                    });
+                    if (counted.outcome === "conflict")
+                        return {
+                            outcome: "invalid",
+                            field: "operationId",
+                            reason: "reused for a different counted request",
+                        };
+                    if (counted.outcome === "invalid")
+                        return counted;
+                    return { outcome: resolution.state, replayed: counted.replayed, operation: null };
+                }
+                const raw = resolution.input, invalid = reserveValidation(raw);
+                if (invalid)
+                    return invalid;
+                // Tags are attribution: sorted here so every adapter stores one canonical order.
+                const tags = raw.scope.tags === undefined ? undefined : normalizeTags(raw.scope.tags), i = tags ? { ...raw, scope: { ...raw.scope, tags } } : raw;
                 if (existing)
                     return store.reserve(i, { budgetOrder: policy.budgetOrder });
                 const statuses = await store.applicableBudgets({
@@ -65,9 +147,39 @@ export function createMeter({ store, policy = defaultPolicy, clock, resolveOwner
         markDispatchIntent: (i) => command(i, () => store.markDispatchIntent(i)),
         renewLease: (i) => command(i, () => store.renewLease(i)),
         claimForRecovery: (i) => command(i, () => store.claimForRecovery(i)),
-        settle: (i) => command(i, () => store.settle(i)),
-        correct: (i) => command(i, () => store.correct(i)),
+        settle: (i) => i.receipt.source === "import"
+            ? Promise.resolve({
+                outcome: "invalid",
+                field: "receipt.source",
+                reason: "import evidence requires the atomic billing import command",
+            })
+            : command(i, () => store.settle(i)),
+        correct: (i) => i.receipt.source === "import"
+            ? Promise.resolve({
+                outcome: "invalid",
+                field: "receipt.source",
+                reason: "import evidence requires the atomic billing import command",
+            })
+            : command(i, () => store.correct(i)),
         releaseUndispatched: (i) => command(i, () => store.releaseUndispatched(i)),
+        countRequest: (i) => {
+            if (i.source === "import")
+                return Promise.resolve({
+                    outcome: "invalid",
+                    field: "source",
+                    reason: "import source is reserved for authorized billing evidence",
+                });
+            const invalid = validate(i) ?? sourceValidation(i);
+            return invalid ? Promise.resolve(invalid) : safely(() => store.countRequest(i));
+        },
+        requestCounts: async (access, q) => {
+            const invalid = requestCountsValidation(q);
+            if (invalid)
+                return invalid;
+            if (!access.canReadBillingDetail || !canRead(access, q.scope))
+                return { outcome: "forbidden" };
+            return read(() => store.requestCounts(q));
+        },
         getOperation: async (access, i) => {
             const invalid = validate(i);
             if (invalid)

package/dist/validation.d.ts

@@ -1,7 +1,12 @@
-import type { ValidationFailure, ReserveInput, UsageQuery, ApplicableBudgetsQuery, OperationsQuery } from "@usagekit/core";
+import type { 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;
 export declare function reserveValidation(i: ReserveInput): ValidationFailure | null;
 export declare function operationsValidation(q: OperationsQuery): ValidationFailure | null;
 export declare function usageValidation(q: UsageQuery): ValidationFailure | null;
+/** Hosts may name the source; a value outside the catalog order is rejected before Store. */
+export declare function provenanceValidation(i: {
+    estimateSource?: string;
+}): ValidationFailure | null;
+export declare function requestCountsValidation(q: RequestCountsQuery): ValidationFailure | null;

package/dist/validation.js

@@ -74,3 +74,14 @@ export function usageValidation(q) {
         };
     return null;
 }
+const estimateSources = ["manual", "measured", "list", "unknown"];
+/** Hosts may name the source; a value outside the catalog order is rejected before Store. */
+export function provenanceValidation(i) {
+    if (i.estimateSource !== undefined &&
+        !estimateSources.includes(i.estimateSource))
+        return { outcome: "invalid", field: "estimateSource", reason: "unknown estimate source" };
+    return null;
+}
+export function requestCountsValidation(q) {
+    return validate(q) ?? windowValidation(q);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usagekit/meter",
-  "version": "0.3.0",
+  "version": "0.5.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.3.0",
-    "@usagekit/store": "0.3.0"
+    "@usagekit/core": "0.5.0",
+    "@usagekit/store": "0.5.0"
   },
   "sideEffects": false,
   "publishConfig": {