@usagekit/meter 0.1.0 → 0.3.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/meter.js

@@ -1,13 +1,14 @@
 import { InvalidInput } from "@usagekit/store";
 import { defaultPolicy } from "./policy.js";
-import { validate, reserveValidation, usageValidation } from "./validation.js";
-import { canRead, canReadBudget } from "./access.js";
+import { validate, reserveValidation, usageValidation, operationsValidation, sourceValidation, } 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, }) {
     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,10 +30,12 @@ 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);
+        reserve: async (raw) => {
+            const 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;
             return safely(async () => {
                 const existing = await store.getOperation({
                     namespace: i.scope.namespace,
@@ -44,6 +47,7 @@ export function createMeter({ store, policy = defaultPolicy, clock, resolveOwner
                 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 } : {}),
                 });
@@ -81,6 +85,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 +102,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 +114,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,7 @@
-import type { ValidationFailure, ReserveInput, UsageQuery } from "@usagekit/core";
+import type { ValidationFailure, ReserveInput, UsageQuery, ApplicableBudgetsQuery, OperationsQuery } 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;

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",

package/package.json

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