@cosmicdrift/kumiko-samples 0.348.1 → 0.349.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-samples",
-  "version": "0.348.1",
+  "version": "0.349.0",
   "description": "Source trees of the Kumiko sample recipes, sample apps and bundled features in repo layout, for tooling such as few-shot corpus builds.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",

package/packages/bundled-features/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.348.1",
+  "version": "0.349.0",
   "description": "Built-in features — tenant, user, auth, delivery. The stuff you'd rewrite anyway, already typed.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",

package/packages/bundled-features/src/metrics/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.349.0",
+    "type": "improvement",
+    "title": "Metrics accept payload filters that narrow the aggregate without replacing the tenant scope",
+    "detail": "metrics: payload filters on a metric\n`MetricDefinition.filters` maps payload keys to source columns, e.g. `{ folderId: \"folderId\" }`. The metric query then accepts that key and narrows the aggregate to the value, for the current and previous window and for groups, stacks and series. The tenant scope is applied last, so a filter value from another tenant yields 0, never that tenant's numbers. `\"\"`, `null` and a missing key mean no filter. The value type follows the column (uuid, numeric, text); an invalid value is a 400. Definitions are rejected at boot for non-camelCase keys, the reserved keys `range`/`timeZone`/`tenantId`, unknown columns, the tenant column, columns already fixed by `where`, and column types other than uuid, text and numeric.\nA filter can also be a resolver `{ column, resolve(value, ctx), valueKind? }`: the payload value (e.g. a folder id) is mapped to the allowed values of `column` through the tenant handler context (IN filter, empty result = no rows), for assignments that live in another table. Resolvers are rejected on metrics with scope `system`."
+  },
   {
     "version": "0.335.0",
     "type": "fix",

package/packages/bundled-features/src/metrics/compute.ts

@@ -22,6 +22,8 @@ export type MetricRunParams = {
   readonly range: MetricRange;
   readonly timeZone: string;
   readonly now: Temporal.Instant;
+  /** Payload-driven narrowing (MetricDefinition.filters); scopeWhere wins on conflicts. */
+  readonly filterWhere: WhereObject;
   /** Extra filter that narrows the source to the caller's scope. */
   readonly scopeWhere: WhereObject;
 };
@@ -68,9 +70,10 @@ type MetricAggregates = {
 function buildWheres(
   metric: MetricDefinition,
   window: MetricWindow | undefined,
+  filterWhere: WhereObject,
   scopeWhere: WhereObject,
 ): MetricWheres {
-  const baseWhere: WhereObject = { ...metric.where, ...scopeWhere };
+  const baseWhere: WhereObject = { ...metric.where, ...filterWhere, ...scopeWhere };
   const { timeField } = metric;
   if (timeField === undefined || window === undefined) {
     return { current: baseWhere, previous: undefined };
@@ -200,7 +203,7 @@ export async function runMetric(
       ? { field: timeField, bucket, timeZone: params.timeZone }
       : undefined;
 
-  const wheres = buildWheres(metric, window, params.scopeWhere);
+  const wheres = buildWheres(metric, window, params.filterWhere, params.scopeWhere);
   const aggregates = await fetchAggregates(db, metric, wheres, bucketDimension);
 
   const value = aggregates.total[0]?.value ?? null;

package/packages/bundled-features/src/metrics/feature.ts

@@ -15,6 +15,11 @@ import {
   METRICS_SYSTEM_FEATURE,
   type MetricScope,
 } from "./constants.js";
+import {
+  metricFilterPayloadShape,
+  metricFilterWhere,
+  resolveMetricFilterWhere,
+} from "./filters.js";
 import { METRICS_I18N } from "./i18n.js";
 import type { MetricDefinition, MetricsFeatureOptions } from "./types.js";
 import { metricHasTenantColumn, validateMetrics } from "./validate.js";
@@ -33,13 +38,21 @@ const invalidTimeZone = {
   message: "Unknown IANA time zone",
 };
 
-const tenantPayloadSchema = z
-  .object(windowFields)
-  .refine((payload) => isValidTimeZone(payload.timeZone), invalidTimeZone);
+function tenantPayloadSchema(metric: MetricDefinition) {
+  return z
+    .object({ ...metricFilterPayloadShape(metric), ...windowFields })
+    .refine((payload) => isValidTimeZone(payload.timeZone), invalidTimeZone);
+}
 
-const systemPayloadSchema = z
-  .object({ ...windowFields, tenantId: z.uuid().optional() })
-  .refine((payload) => isValidTimeZone(payload.timeZone), invalidTimeZone);
+function systemPayloadSchema(metric: MetricDefinition) {
+  return z
+    .object({
+      ...metricFilterPayloadShape(metric),
+      ...windowFields,
+      tenantId: z.uuid().optional(),
+    })
+    .refine((payload) => isValidTimeZone(payload.timeZone), invalidTimeZone);
+}
 
 const defaultClock = (): Temporal.Instant => Temporal.Now.instant();
 
@@ -64,13 +77,14 @@ function createTenantMetricQuery(
   return defineQueryHandler({
     name: metric.id,
     description: metric.description,
-    schema: tenantPayloadSchema,
+    schema: tenantPayloadSchema(metric),
     access: { roles: access.admin },
-    handler: (query, ctx) =>
+    handler: async (query, ctx) =>
       runMetric(ctx.db, metric, {
         range: query.payload.range,
         timeZone: query.payload.timeZone,
         now: now(),
+        filterWhere: await resolveMetricFilterWhere(metric, query.payload, ctx),
         // ctx.db already reads own-tenant + SYSTEM reference rows; this narrows to own-tenant only.
         scopeWhere: { tenantId: query.user.tenantId },
       }),
@@ -84,7 +98,7 @@ function createSystemMetricQuery(
   return defineQueryHandler({
     name: metric.id,
     description: metric.description,
-    schema: systemPayloadSchema,
+    schema: systemPayloadSchema(metric),
     access: { roles: access.systemAdmin },
     handler: (query, ctx) => {
       if (!ctx.systemDb) {
@@ -111,6 +125,7 @@ function createSystemMetricQuery(
         range: query.payload.range,
         timeZone: query.payload.timeZone,
         now: now(),
+        filterWhere: metricFilterWhere(metric, query.payload),
         scopeWhere: tenantId === undefined ? {} : { tenantId },
       });
     },

package/packages/bundled-features/src/metrics/filters.ts

@@ -0,0 +1,100 @@
+import { extractTableInfo, type WhereObject } from "@cosmicdrift/kumiko-framework/bun-db";
+import type { HandlerContext } from "@cosmicdrift/kumiko-framework/engine";
+import * as z from "zod";
+import type { MetricDefinition, MetricFilterResolver } from "./types.js";
+
+export const RESERVED_PAYLOAD_KEYS: readonly string[] = ["range", "timeZone", "tenantId"];
+
+// Dashboard select options always send strings.
+const NUMERIC_STRING = /^-?\d+(\.\d+)?$/;
+const MAX_FILTER_STRING_LENGTH = 200;
+const NUMERIC_PG_TYPES: ReadonlySet<string> = new Set([
+  "integer",
+  "int4",
+  "smallint",
+  "int2",
+  "bigint",
+  "serial",
+  "bigserial",
+  "double precision",
+]);
+
+export type FilterValueKind = "uuid" | "number" | "string";
+
+/** Undefined = the column type cannot be filtered by a payload value without risking a Postgres cast error. */
+export function filterValueKindOf(pgType: string | undefined): FilterValueKind | undefined {
+  if (pgType === undefined) return undefined;
+  if (pgType === "uuid") return "uuid";
+  if (pgType === "text") return "string";
+  if (NUMERIC_PG_TYPES.has(pgType) || pgType.startsWith("numeric")) return "number";
+  return undefined;
+}
+
+export type MetricFilterEntry = {
+  readonly payloadKey: string;
+  readonly column: string;
+  readonly resolver?: MetricFilterResolver;
+};
+
+export function metricFilterEntries(metric: MetricDefinition): readonly MetricFilterEntry[] {
+  return Object.entries(metric.filters ?? {}).map(([payloadKey, spec]) =>
+    typeof spec === "string"
+      ? { payloadKey, column: spec }
+      : { payloadKey, column: spec.column, resolver: spec },
+  );
+}
+
+function filterValueSchema(kind: FilterValueKind): z.ZodType {
+  if (kind === "uuid") return z.uuid();
+  if (kind === "number")
+    return z.union([z.number(), z.string().regex(NUMERIC_STRING).transform(Number)]);
+  return z.string().min(1).max(MAX_FILTER_STRING_LENGTH);
+}
+
+/** "" and null mean "no filter" (the dashboard's "(all)" option). */
+export function metricFilterPayloadShape(metric: MetricDefinition): Record<string, z.ZodType> {
+  const info = extractTableInfo(metric.source);
+  const shape: Record<string, z.ZodType> = {};
+  for (const { payloadKey, column, resolver } of metricFilterEntries(metric)) {
+    const kind =
+      resolver !== undefined
+        ? (resolver.valueKind ?? "string")
+        : filterValueKindOf(info.pgTypeOf(info.columnOf(column)));
+    if (kind === undefined) continue;
+    shape[payloadKey] = z.union([z.literal(""), z.null(), filterValueSchema(kind)]).optional();
+  }
+  return shape;
+}
+
+function activeFilterValue(payload: Readonly<Record<string, unknown>>, key: string): unknown {
+  const value = payload[key];
+  return value === undefined || value === null || value === "" ? undefined : value;
+}
+
+/** Column-equality filters only; resolver filters need resolveMetricFilterWhere. */
+export function metricFilterWhere(
+  metric: MetricDefinition,
+  payload: Readonly<Record<string, unknown>>,
+): WhereObject {
+  const where: WhereObject = {};
+  for (const { payloadKey, column, resolver } of metricFilterEntries(metric)) {
+    const value = activeFilterValue(payload, payloadKey);
+    if (resolver === undefined && value !== undefined) where[column] = value;
+  }
+  return where;
+}
+
+export async function resolveMetricFilterWhere(
+  metric: MetricDefinition,
+  payload: Readonly<Record<string, unknown>>,
+  ctx: HandlerContext,
+): Promise<WhereObject> {
+  const where = metricFilterWhere(metric, payload);
+  for (const { payloadKey, column, resolver } of metricFilterEntries(metric)) {
+    const value = activeFilterValue(payload, payloadKey);
+    if (resolver === undefined || (typeof value !== "string" && typeof value !== "number"))
+      continue;
+    where[column] = await resolver.resolve(value, ctx);
+  }
+  return where;
+}

package/packages/bundled-features/src/metrics/index.ts

@@ -24,6 +24,7 @@ export { METRICS_I18N } from "./i18n.js";
 export {
   defineMetric,
   type MetricDefinition,
+  type MetricFilterResolver,
   type MetricPoint,
   type MetricResult,
   type MetricRow,

package/packages/bundled-features/src/metrics/types.ts

@@ -1,4 +1,5 @@
 import type { EntityTableMeta } from "@cosmicdrift/kumiko-framework/db";
+import type { HandlerContext } from "@cosmicdrift/kumiko-framework/engine";
 import type {
   AggregateMeasure,
   AggregateTimeBucket,
@@ -8,6 +9,17 @@ import type { WhereObject } from "@cosmicdrift/kumiko-types/where-clause-types";
 import type { Temporal } from "temporal-polyfill";
 import type { MetricRange, MetricScope } from "./constants.js";
 
+/** Maps a payload value (e.g. a folder id) to the values `column` may have (e.g. the folder and its subfolders' loan ids). Runs with the tenant handler context, so reads stay tenant-scoped; the result only narrows. An empty result yields no rows. */
+export type MetricFilterResolver = {
+  readonly column: string;
+  readonly resolve: (
+    value: string | number,
+    ctx: HandlerContext,
+  ) => Promise<readonly (string | number)[]>;
+  /** Type of the payload value, not of `column`. Default "string". */
+  readonly valueKind?: "uuid" | "number" | "string";
+};
+
 export type MetricDefinition = {
   readonly id: string;
   readonly description: string;
@@ -16,6 +28,8 @@ export type MetricDefinition = {
   readonly requires?: string;
   readonly measure: AggregateMeasure;
   readonly where?: WhereObject;
+  /** Payload key → source column (equality) or a resolver (IN). e.g. `{ folderId: "folderId" }`. Narrows the result only; the tenant scope is always applied on top and never replaced. Resolvers need a metric without scope "system". */
+  readonly filters?: Readonly<Record<string, string | MetricFilterResolver>>;
   /** timestamptz column; without it the metric is a snapshot with no window. */
   readonly timeField?: string;
   /** Fixed window, ignores the payload range. */

package/packages/bundled-features/src/metrics/validate.ts

@@ -1,8 +1,10 @@
 import { extractTableInfo, isTimestamptzType } from "@cosmicdrift/kumiko-framework/bun-db";
 import { METRIC_RANGES } from "./constants.js";
+import { filterValueKindOf, metricFilterEntries, RESERVED_PAYLOAD_KEYS } from "./filters.js";
 import type { MetricDefinition } from "./types.js";
 
 const KEBAB_ID = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
+const FILTER_PAYLOAD_KEY = /^[a-z][a-zA-Z0-9]*$/;
 const TENANT_ID_FIELD = "tenantId";
 
 export function metricHasTenantColumn(metric: MetricDefinition): boolean {
@@ -32,6 +34,7 @@ function validateMetric(metric: MetricDefinition): void {
 
   const info = extractTableInfo(metric.source);
   validateColumns(metric, info, fail);
+  validateFilters(metric, info, fail);
   validateTimeSettings(metric, info, fail);
   validateShape(metric, fail);
   if (metric.scopes.includes("tenant") && !metricHasTenantColumn(metric)) {
@@ -50,6 +53,37 @@ function validateColumns(metric: MetricDefinition, info: TableInfo, fail: Fail):
   if (metric.timeField !== undefined) requireColumn(metric.timeField, "timeField");
 }
 
+function validateFilters(metric: MetricDefinition, info: TableInfo, fail: Fail): void {
+  const baseWhereColumns = new Set(Object.keys(metric.where ?? {}).map((f) => info.columnOf(f)));
+  for (const { payloadKey, column: field, resolver } of metricFilterEntries(metric)) {
+    if (resolver !== undefined && metric.scopes.includes("system")) {
+      fail(
+        `filter "${payloadKey}" uses a resolver, which runs with the tenant context and cannot be combined with scope "system"`,
+      );
+    }
+    if (!FILTER_PAYLOAD_KEY.test(payloadKey)) {
+      fail(`has filter key "${payloadKey}" that is not a camelCase identifier`);
+    }
+    if (RESERVED_PAYLOAD_KEYS.includes(payloadKey)) {
+      fail(`has filter key "${payloadKey}" that is reserved by the metric payload`);
+    }
+    if (!info.hasColumn(field))
+      fail(`filter "${payloadKey}" column "${field}" is not a column of ${info.name}`);
+    const column = info.columnOf(field);
+    if (column === info.columnOf(TENANT_ID_FIELD)) {
+      fail(`filter "${payloadKey}" targets the tenant column, which only the scope may set`);
+    }
+    if (baseWhereColumns.has(column)) {
+      fail(`filter "${payloadKey}" column "${field}" is already fixed by the metric where`);
+    }
+    if (filterValueKindOf(info.pgTypeOf(column)) === undefined) {
+      fail(
+        `filter "${payloadKey}" column "${field}" has type ${info.pgTypeOf(column)}, only uuid, text and numeric columns can be filtered`,
+      );
+    }
+  }
+}
+
 function validateTimeSettings(metric: MetricDefinition, info: TableInfo, fail: Fail): void {
   const { timeField } = metric;
   if (timeField === undefined) {