@usagekit/meter 0.1.0 → 0.4.0

package/dist/access.d.ts

@@ -5,4 +5,15 @@ export type OwnershipResolver = (scope: Extract<BudgetScope, {
 }>) => Promise<BudgetOwner | null>;
 export declare const includes: (list: readonly string[] | "*", id: string) => boolean;
 export declare function canRead(access: AccessContext, scope: UsageScope): boolean;
+/** Pools and tags span principals: their figures are shared, so unreadable ones are redacted, not forbidden. */
+export declare const isShared: (scope: BudgetScope) => scope is {
+    kind: "platform_pool";
+    namespace: string;
+    poolId: string;
+} | {
+    kind: "tag";
+    namespace: string;
+    tag: string;
+};
+export declare function canReadShared(access: AccessContext, scope: BudgetScope): boolean;
 export declare function canReadBudget(resolveOwnership: OwnershipResolver | undefined, access: AccessContext, scope: BudgetScope): Promise<boolean>;

package/dist/access.js

@@ -13,9 +13,20 @@ export function canRead(access, scope) {
             return access.canManageBudgets || includes(access.readablePools, scope.poolId);
     }
 }
+/** Pools and tags span principals: their figures are shared, so unreadable ones are redacted, not forbidden. */
+export const isShared = (scope) => scope.kind === "platform_pool" || scope.kind === "tag";
+export function canReadShared(access, scope) {
+    if (access.namespace !== scope.namespace)
+        return false;
+    if (scope.kind === "platform_pool")
+        return canRead(access, scope);
+    return access.canManageBudgets || access.readablePrincipals === "*";
+}
 export async function canReadBudget(resolveOwnership, access, scope) {
     if (access.namespace !== scope.namespace)
         return false;
+    if (isShared(scope))
+        return canReadShared(access, scope);
     if (scope.kind !== "connection" && scope.kind !== "access_credential")
         return canRead(access, scope);
     const owner = await resolveOwnership?.(scope);

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,13 +1,15 @@
+import { resolveReserve } from "./catalog.js";
 import { InvalidInput } from "@usagekit/store";
 import { defaultPolicy } from "./policy.js";
-import { validate, reserveValidation, usageValidation } from "./validation.js";
-import { canRead, canReadBudget } from "./access.js";
-export function createMeter({ store, policy = defaultPolicy, clock, resolveOwnership, }) {
+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, catalog, resolveConnection, }) {
     if (!Number.isFinite(clock.now().getTime()))
         throw new Error("InvalidInput: clock");
-    if (policy.budgetOrder.length !== 5 ||
-        new Set(policy.budgetOrder).size !== 5 ||
-        policy.budgetOrder.some((k) => !defaultPolicy.budgetOrder.includes(k)))
+    if (policy.budgetOrder.length !== defaultBudgetOrder.length ||
+        new Set(policy.budgetOrder).size !== defaultBudgetOrder.length ||
+        policy.budgetOrder.some((k) => !defaultBudgetOrder.includes(k)))
         throw new Error("InvalidInput: budgetOrder");
     async function safely(fn) {
         try {
@@ -29,21 +31,54 @@ 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 (i) => {
-            const invalid = reserveValidation(i);
-            if (invalid)
-                return invalid;
+        reserve: async (requested) => {
+            const early = validate({ ...requested, estimate: requested.estimate ?? [] }) ??
+                sourceValidation(requested) ??
+                provenanceValidation(requested);
+            if (early)
+                return early;
             return safely(async () => {
                 const existing = await store.getOperation({
-                    namespace: i.scope.namespace,
-                    principal: i.scope.principal,
-                    operationId: i.operationId,
+                    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({
                     scope: i.scope,
                     surface: i.surface,
+                    source: i.source,
                     units: i.estimate.map((q) => q.unit),
                     ...(i.platformPools ? { platformPools: i.platformPools } : {}),
                 });
@@ -64,6 +99,18 @@ export function createMeter({ store, policy = defaultPolicy, clock, resolveOwner
         settle: (i) => command(i, () => store.settle(i)),
         correct: (i) => command(i, () => store.correct(i)),
         releaseUndispatched: (i) => command(i, () => store.releaseUndispatched(i)),
+        countRequest: (i) => {
+            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)
@@ -81,6 +128,14 @@ export function createMeter({ store, policy = defaultPolicy, clock, resolveOwner
                 return { outcome: "forbidden" };
             return read(() => store.aggregate(q));
         },
+        listOperations: async (access, q) => {
+            const invalid = operationsValidation(q);
+            if (invalid)
+                return invalid;
+            if (!access.canReadBillingDetail || !canRead(access, q.scope))
+                return { outcome: "forbidden" };
+            return read(() => store.listOperations(q));
+        },
         definedBudgets: async (access, q) => {
             const invalid = validate(q);
             if (invalid)
@@ -90,7 +145,7 @@ export function createMeter({ store, policy = defaultPolicy, clock, resolveOwner
             return read(() => store.definedBudgets(q));
         },
         applicableBudgets: async (access, q) => {
-            const invalid = validate(q);
+            const invalid = validate(q) ?? sourceValidation(q);
             if (invalid)
                 return invalid;
             if (!canRead(access, {
@@ -102,13 +157,13 @@ export function createMeter({ store, policy = defaultPolicy, clock, resolveOwner
             return safely(async () => {
                 const rows = await store.applicableBudgets(q);
                 for (const status of rows) {
-                    if (status.budget.scope.kind !== "platform_pool" &&
+                    if (!isShared(status.budget.scope) &&
                         !(await canReadBudget(resolveOwnership, access, status.budget.scope)))
                         return { outcome: "forbidden" };
                 }
                 return {
                     outcome: "ok",
-                    value: rows.map((s) => s.budget.scope.kind === "platform_pool" && !canRead(access, s.budget.scope)
+                    value: rows.map((s) => isShared(s.budget.scope) && !canReadShared(access, s.budget.scope)
                         ? {
                             ...s,
                             budget: { ...s.budget, limit: null },

package/dist/validation.d.ts

@@ -1,4 +1,12 @@
-import type { ValidationFailure, ReserveInput, UsageQuery } 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

@@ -1,3 +1,4 @@
+import { sourcesOf, normalizeTags } from "@usagekit/core";
 export function validate(value, field = "input") {
     const fail = (reason) => ({ outcome: "invalid", field, reason });
     if (typeof value === "string" && !value.trim())
@@ -22,24 +23,49 @@ export function validate(value, field = "input") {
     }
     return null;
 }
+/** The host sets both fields at authentication; a source outside its surface group is a forgery or a bug. */
+export function sourceValidation(i) {
+    if (i.source !== undefined && !sourcesOf(i.surface)?.includes(i.source))
+        return { outcome: "invalid", field: "source", reason: "source outside surface group" };
+    return null;
+}
 export function reserveValidation(i) {
-    const error = validate(i);
+    const error = validate(i) ?? sourceValidation(i);
     if (error)
         return error;
+    if (i.scope.tags !== undefined && !normalizeTags(i.scope.tags))
+        return {
+            outcome: "invalid",
+            field: "scope.tags",
+            reason: "1 to 16 unique tags matching the tag pattern",
+        };
     if (new Set(i.estimate.map((q) => q.unit)).size !== i.estimate.length)
         return { outcome: "invalid", field: "estimate", reason: "duplicate unit" };
     return null;
 }
-export function usageValidation(q) {
-    const error = validate(q);
-    if (error)
-        return error;
+const lifecycle = ["reserved", "dispatch_intended", "pending", "settled", "released"];
+function windowValidation(q) {
     if (!Number.isFinite(Date.parse(q.from)) ||
         !Number.isFinite(Date.parse(q.to)) ||
         Date.parse(q.from) > Date.parse(q.to))
         return { outcome: "invalid", field: "window", reason: "invalid time interval" };
     if (q.limit !== undefined && (q.limit < 1 || q.limit > 1000))
         return { outcome: "invalid", field: "limit", reason: "must be between 1 and 1000" };
+    return null;
+}
+export function operationsValidation(q) {
+    const error = validate(q) ?? windowValidation(q);
+    if (error)
+        return error;
+    if (q.states !== undefined &&
+        (q.states.length < 1 || q.states.some((state) => !lifecycle.includes(state))))
+        return { outcome: "invalid", field: "states", reason: "one or more lifecycle states" };
+    return null;
+}
+export function usageValidation(q) {
+    const error = validate(q) ?? windowValidation(q);
+    if (error)
+        return error;
     if (q.groupBy.includes("principal") && !["namespace", "group"].includes(q.scope.kind))
         return {
             outcome: "invalid",
@@ -48,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.1.0",
+  "version": "0.4.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.1.0",
-    "@usagekit/store": "0.1.0"
+    "@usagekit/core": "0.4.0",
+    "@usagekit/store": "0.4.0"
   },
   "sideEffects": false,
   "publishConfig": {