@cosmicdrift/kumiko-bundled-features 0.329.0 → 0.330.2

package/dist/jobs/feature.js

@@ -132,7 +132,7 @@ export function createJobsFeature(options = {}) {
             layout: { sections: [{ fields: ["jobName", "payload"] }] },
             submitLabel: i18nKey("jobs.trigger.submit"),
             access: systemAdminAccess,
-            description: "Manually trigger a job by name with an optional JSON object payload.",
+            description: "jobs.screen.job-trigger.subtitle",
         });
         r.screen({
             id: JOB_RUN_DETAIL_SCREEN_ID,
@@ -181,7 +181,7 @@ export function createJobsFeature(options = {}) {
                     style: "primary",
                 },
             ],
-            description: "Detail view of one job run with status, timings, error and log lines, and a retry action for failed runs; reached from a row of the job-runs list.",
+            description: "jobs.screen.job-run-detail.subtitle",
             listScreenId: JOB_RUNS_SCREEN_ID,
             access: systemAdminAccess,
         });

package/dist/jobs/i18n.js

@@ -4,6 +4,12 @@ export const JOBS_I18N = {
     "screen:job-runs.title": { en: "Job runs" },
     "screen:job-run-detail.title": { en: "Job run" },
     "screen:job-trigger.title": { en: "Trigger job" },
+    "jobs.screen.job-trigger.subtitle": {
+        en: "Start a job manually by name, with an optional JSON payload.",
+    },
+    "jobs.screen.job-run-detail.subtitle": {
+        en: "Status, timings, error and log lines of one job run.",
+    },
     "jobs:entity:__action-form__:field:jobName": { en: "Job name" },
     "jobs:entity:__action-form__:field:payload": { en: "JSON payload" },
     "jobs:nav.jobRuns": { en: "Jobs" },

package/dist/jobs/job-run-table.js

@@ -40,6 +40,7 @@ export const jobRunEntity = createEntity({
         duration: createNumberField({ integer: true }),
         triggeredById: createTextField({ personal: false, reason: "pseudonymous_fk" }),
     },
+    indexes: [{ columns: ["startedAt"] }],
 });
 // Plain EntityTableMeta, NOT a branded EntityTable (buildEntityTable would
 // mark it executor-only): job-run is an unmanaged direct-write store, so

package/dist/metrics/compute.d.ts

@@ -0,0 +1,13 @@
+import type { WhereObject } from "@cosmicdrift/kumiko-framework/bun-db";
+import type { TenantDb } from "@cosmicdrift/kumiko-types/tenant-db-types";
+import type { Temporal } from "temporal-polyfill";
+import { type MetricRange } from "./constants.js";
+import type { MetricDefinition, MetricResult } from "./types.js";
+export type MetricRunParams = {
+    readonly range: MetricRange;
+    readonly timeZone: string;
+    readonly now: Temporal.Instant;
+    /** Extra filter that narrows the source to the caller's scope. */
+    readonly scopeWhere: WhereObject;
+};
+export declare function runMetric(db: TenantDb, metric: MetricDefinition, params: MetricRunParams): Promise<MetricResult>;

package/dist/metrics/compute.js

@@ -0,0 +1,127 @@
+import { MAX_GROUP_ROWS } from "./constants.js";
+import { bucketStartsMs, computeWindow, resolveBucket } from "./window.js";
+const NULL_KEY_TEXT = "—";
+function keyText(key) {
+    return key === null || key === undefined ? NULL_KEY_TEXT : String(key);
+}
+function formatDelta(value, previousValue) {
+    if (value === null || previousValue === null || previousValue === 0 || value === previousValue) {
+        return { delta: null, deltaDirection: null };
+    }
+    const percent = Math.round((Math.abs(value - previousValue) / Math.abs(previousValue)) * 100);
+    if (percent === 0)
+        return { delta: null, deltaDirection: null };
+    return { delta: `${percent} %`, deltaDirection: value > previousValue ? "up" : "down" };
+}
+function fractionOf(value, total) {
+    if (total === null || total <= 0)
+        return 0;
+    return Math.min(1, Math.max(0, value / total));
+}
+function buildWheres(metric, window, scopeWhere) {
+    const baseWhere = { ...metric.where, ...scopeWhere };
+    const { timeField } = metric;
+    if (timeField === undefined || window === undefined) {
+        return { current: baseWhere, previous: undefined };
+    }
+    return {
+        current: { ...baseWhere, [timeField]: { gte: window.start, lte: window.end } },
+        previous: metric.comparePrevious === false
+            ? undefined
+            : { ...baseWhere, [timeField]: { gte: window.previousStart, lt: window.start } },
+    };
+}
+async function fetchAggregates(db, metric, wheres, bucketDimension) {
+    const aggregate = (groupBy, where, extra = {}) => db.aggregate(metric.source, { measure: metric.measure, groupBy, ...extra }, where);
+    const { groupBy, stackBy } = metric;
+    const { current } = wheres;
+    const [total, previous, points, groups, stacks, series] = await Promise.all([
+        aggregate([], current),
+        wheres.previous === undefined ? Promise.resolve(undefined) : aggregate([], wheres.previous),
+        bucketDimension !== undefined && groupBy === undefined
+            ? aggregate([bucketDimension], current)
+            : Promise.resolve([]),
+        groupBy === undefined
+            ? Promise.resolve([])
+            : aggregate([{ field: groupBy }], current, { orderByValue: "desc", limit: MAX_GROUP_ROWS }),
+        groupBy !== undefined && stackBy !== undefined
+            ? aggregate([{ field: groupBy }, { field: stackBy }], current)
+            : Promise.resolve([]),
+        bucketDimension !== undefined && groupBy !== undefined
+            ? aggregate([{ field: groupBy }, bucketDimension], current)
+            : Promise.resolve([]),
+    ]);
+    return { total, previous, points, groups, stacks, series };
+}
+function groupSegments(stackRows, labelOf) {
+    const segmentsByGroup = new Map();
+    for (const row of stackRows) {
+        const groupKey = keyText(row.keys[0]);
+        const stackKey = keyText(row.keys[1]);
+        const segments = segmentsByGroup.get(groupKey) ?? [];
+        segments.push({ key: stackKey, label: labelOf(stackKey), value: row.value ?? 0 });
+        segmentsByGroup.set(groupKey, segments);
+    }
+    return segmentsByGroup;
+}
+function buildRows(metric, aggregates, total, labelOf) {
+    const segmentsByGroup = groupSegments(aggregates.stacks, labelOf);
+    return aggregates.groups.map((row) => {
+        const key = keyText(row.keys[0]);
+        const rowValue = row.value ?? 0;
+        return {
+            id: key,
+            key,
+            label: labelOf(key),
+            value: rowValue,
+            fraction: fractionOf(rowValue, total),
+            ...(metric.stackBy !== undefined && { segments: segmentsByGroup.get(key) ?? [] }),
+        };
+    });
+}
+function buildSeries(rows, seriesRows, fillBuckets) {
+    const bucketsByGroup = new Map();
+    for (const row of seriesRows) {
+        const groupKey = keyText(row.keys[0]);
+        const buckets = bucketsByGroup.get(groupKey) ?? new Map();
+        buckets.set(Number(row.keys[1]), row.value);
+        bucketsByGroup.set(groupKey, buckets);
+    }
+    return rows.map((row) => ({
+        key: row.key,
+        label: row.label,
+        points: fillBuckets(bucketsByGroup.get(row.key) ?? new Map()),
+    }));
+}
+export async function runMetric(db, metric, params) {
+    const range = metric.window ?? params.range;
+    const bucket = resolveBucket(metric, range);
+    const { timeField } = metric;
+    const window = timeField === undefined ? undefined : computeWindow(range, bucket, params.timeZone, params.now);
+    const bucketDimension = timeField !== undefined && bucket !== undefined
+        ? { field: timeField, bucket, timeZone: params.timeZone }
+        : undefined;
+    const wheres = buildWheres(metric, window, params.scopeWhere);
+    const aggregates = await fetchAggregates(db, metric, wheres, bucketDimension);
+    const value = aggregates.total[0]?.value ?? null;
+    const previousValue = aggregates.previous?.[0]?.value ?? null;
+    const labelOf = (key) => metric.groupLabels?.[key] ?? key;
+    const gapValue = metric.measure.fn === "avg" ? null : 0;
+    const bucketStarts = window !== undefined && bucket !== undefined
+        ? bucketStartsMs(window, bucket, params.timeZone)
+        : [];
+    const fillBuckets = (byBucketMs) => bucketStarts.map((atMs) => ({ atMs, value: byBucketMs.get(atMs) ?? gapValue }));
+    const points = fillBuckets(new Map(aggregates.points.map((row) => [Number(row.keys[0]), row.value])));
+    const rows = buildRows(metric, aggregates, value, labelOf);
+    return {
+        value,
+        previousValue,
+        ...formatDelta(value, previousValue),
+        windowStartMs: window?.start.epochMilliseconds ?? null,
+        windowEndMs: window?.end.epochMilliseconds ?? null,
+        points,
+        series: buildSeries(rows, aggregates.series, fillBuckets),
+        rows,
+        nextCursor: null,
+    };
+}

package/dist/metrics/constants.d.ts

@@ -0,0 +1,7 @@
+export declare const METRICS_FEATURE: "metrics";
+export declare const METRICS_SYSTEM_FEATURE: "metrics-system";
+export type MetricScope = "system" | "tenant";
+export declare function metricQueryName(scope: MetricScope, id: string): string;
+export declare const METRIC_RANGES: readonly ["24h", "7d", "14d", "30d"];
+export type MetricRange = (typeof METRIC_RANGES)[number];
+export declare const MAX_GROUP_ROWS = 50;

package/dist/metrics/constants.js

@@ -0,0 +1,14 @@
+// @runtime client
+// Pure constants — imported by server (feature.ts) and by panel declarations,
+// so no runtime import from the engine barrel here.
+export const METRICS_FEATURE = "metrics";
+export const METRICS_SYSTEM_FEATURE = "metrics-system";
+const FEATURE_BY_SCOPE = {
+    tenant: METRICS_FEATURE,
+    system: METRICS_SYSTEM_FEATURE,
+};
+export function metricQueryName(scope, id) {
+    return `${FEATURE_BY_SCOPE[scope]}:query:${id}`;
+}
+export const METRIC_RANGES = ["24h", "7d", "14d", "30d"];
+export const MAX_GROUP_ROWS = 50;

package/dist/metrics/default-metrics.d.ts

@@ -0,0 +1,9 @@
+export declare const jobRunsByStatusMetric: import("./types.js").MetricDefinition;
+export declare const failedJobRunsMetric: import("./types.js").MetricDefinition;
+export declare const tenantJobFailuresMetric: import("./types.js").MetricDefinition;
+export declare const deliveriesByChannelMetric: import("./types.js").MetricDefinition;
+export declare const failedDeliveriesMetric: import("./types.js").MetricDefinition;
+export declare const activeUsersMetric: import("./types.js").MetricDefinition;
+export declare const activeTenantsMetric: import("./types.js").MetricDefinition;
+export declare const auditWritesMetric: import("./types.js").MetricDefinition;
+export declare const DEFAULT_METRICS: readonly [import("./types.js").MetricDefinition, import("./types.js").MetricDefinition, import("./types.js").MetricDefinition, import("./types.js").MetricDefinition, import("./types.js").MetricDefinition, import("./types.js").MetricDefinition, import("./types.js").MetricDefinition, import("./types.js").MetricDefinition];

package/dist/metrics/default-metrics.js

@@ -0,0 +1,115 @@
+import { eventsTable } from "@cosmicdrift/kumiko-framework/event-store";
+import { DELIVERY_FEATURE, DeliveryStatus, deliveryAttemptsTable } from "../delivery/index.js";
+import { JOBS_FEATURE, jobRunsTable, tenantJobFailuresTable, } from "../jobs/index.js";
+import { SESSIONS_FEATURE, userSessionTable } from "../sessions/index.js";
+import { TENANT_FEATURE, tenantTable } from "../tenant/index.js";
+import { defineMetric } from "./types.js";
+const JOB_STATUSES = ["queued", "running", "completed", "failed"];
+function labelKeys(prefix, keys) {
+    return Object.fromEntries(keys.map((key) => [key, `${prefix}.${key}`]));
+}
+const JOB_STATUS_LABELS = labelKeys("metrics:jobStatus", JOB_STATUSES);
+const DELIVERY_STATUS_LABELS = labelKeys("metrics:deliveryStatus", Object.values(DeliveryStatus));
+// Channel ids are open (extension point), so only the bundled ones are mapped;
+// unknown channels fall back to their raw id. Shared map: labelOf serves groupBy and stackBy.
+const DELIVERY_CHANNEL_LABELS = labelKeys("metrics:deliveryChannel", ["inApp", "email", "push"]);
+export const jobRunsByStatusMetric = defineMetric({
+    id: "job-runs-by-status",
+    description: "Counts job runs started in the window, split by status over time.",
+    source: jobRunsTable,
+    requires: JOBS_FEATURE,
+    measure: { fn: "count" },
+    timeField: "startedAt",
+    bucket: "auto",
+    groupBy: "status",
+    groupLabels: JOB_STATUS_LABELS,
+    scopes: ["system"],
+});
+export const failedJobRunsMetric = defineMetric({
+    id: "failed-job-runs",
+    description: "Counts failed job runs over the last 24 hours, per hour.",
+    source: jobRunsTable,
+    requires: JOBS_FEATURE,
+    measure: { fn: "count" },
+    where: { status: "failed" },
+    timeField: "startedAt",
+    window: "24h",
+    bucket: "hour",
+    scopes: ["system"],
+});
+export const tenantJobFailuresMetric = defineMetric({
+    id: "tenant-job-failures",
+    description: "Counts tenant-attributed job failures over the last 24 hours, per hour.",
+    source: tenantJobFailuresTable,
+    requires: JOBS_FEATURE,
+    measure: { fn: "count" },
+    timeField: "failedAt",
+    window: "24h",
+    bucket: "hour",
+    scopes: ["tenant", "system"],
+});
+export const deliveriesByChannelMetric = defineMetric({
+    id: "deliveries-by-channel",
+    description: "Counts notification delivery attempts in the window per channel, stacked by status.",
+    source: deliveryAttemptsTable,
+    requires: DELIVERY_FEATURE,
+    measure: { fn: "count" },
+    timeField: "createdAt",
+    groupBy: "channel",
+    stackBy: "status",
+    groupLabels: { ...DELIVERY_CHANNEL_LABELS, ...DELIVERY_STATUS_LABELS },
+    scopes: ["tenant", "system"],
+});
+export const failedDeliveriesMetric = defineMetric({
+    id: "failed-deliveries",
+    description: "Counts failed notification delivery attempts over the last 24 hours, per hour.",
+    source: deliveryAttemptsTable,
+    requires: DELIVERY_FEATURE,
+    measure: { fn: "count" },
+    where: { status: DeliveryStatus.failed },
+    timeField: "createdAt",
+    window: "24h",
+    bucket: "hour",
+    scopes: ["tenant", "system"],
+});
+export const activeUsersMetric = defineMetric({
+    id: "active-users",
+    description: "Counts distinct users with session activity over the last 7 days, per day.",
+    source: userSessionTable,
+    requires: SESSIONS_FEATURE,
+    measure: { fn: "countDistinct", field: "userId" },
+    timeField: "lastSeenAt",
+    window: "7d",
+    bucket: "day",
+    comparePrevious: false,
+    scopes: ["tenant", "system"],
+});
+export const activeTenantsMetric = defineMetric({
+    id: "active-tenants",
+    description: "Counts tenants that are enabled and in the active lifecycle state.",
+    source: tenantTable,
+    requires: TENANT_FEATURE,
+    measure: { fn: "count" },
+    where: { isEnabled: true, status: "active" },
+    scopes: ["system"],
+});
+export const auditWritesMetric = defineMetric({
+    id: "audit-writes",
+    description: "Counts event-store writes over the last 14 days, per day.",
+    source: eventsTable,
+    measure: { fn: "count" },
+    timeField: "createdAt",
+    window: "14d",
+    bucket: "day",
+    scopes: ["tenant", "system"],
+});
+export const DEFAULT_METRICS = [
+    jobRunsByStatusMetric,
+    failedJobRunsMetric,
+    tenantJobFailuresMetric,
+    deliveriesByChannelMetric,
+    failedDeliveriesMetric,
+    activeUsersMetric,
+    activeTenantsMetric,
+    auditWritesMetric,
+];

package/dist/metrics/feature.d.ts

@@ -0,0 +1,4 @@
+import { type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
+import type { MetricsFeatureOptions } from "./types.js";
+export declare function createMetricsFeature(options: MetricsFeatureOptions): FeatureDefinition;
+export declare function createSystemMetricsFeature(options: MetricsFeatureOptions): FeatureDefinition;

package/dist/metrics/feature.js

@@ -0,0 +1,119 @@
+import { access, defineFeature, defineQueryHandler, } from "@cosmicdrift/kumiko-framework/engine";
+import { InternalError, ValidationError } from "@cosmicdrift/kumiko-framework/errors";
+import { Temporal } from "temporal-polyfill";
+import * as z from "zod";
+import { runMetric } from "./compute.js";
+import { METRIC_RANGES, METRICS_FEATURE, METRICS_SYSTEM_FEATURE, } from "./constants.js";
+import { METRICS_I18N } from "./i18n.js";
+import { metricHasTenantColumn, validateMetrics } from "./validate.js";
+import { isValidTimeZone } from "./window.js";
+const DEFAULT_RANGE = "7d";
+const DEFAULT_TIME_ZONE = "UTC";
+const windowFields = {
+    range: z.enum(METRIC_RANGES).default(DEFAULT_RANGE),
+    timeZone: z.string().default(DEFAULT_TIME_ZONE),
+};
+const invalidTimeZone = {
+    path: ["timeZone"],
+    message: "Unknown IANA time zone",
+};
+const tenantPayloadSchema = z
+    .object(windowFields)
+    .refine((payload) => isValidTimeZone(payload.timeZone), invalidTimeZone);
+const systemPayloadSchema = z
+    .object({ ...windowFields, tenantId: z.uuid().optional() })
+    .refine((payload) => isValidTimeZone(payload.timeZone), invalidTimeZone);
+const defaultClock = () => Temporal.Now.instant();
+function metricsForScope(metrics, scope) {
+    return metrics.filter((metric) => metric.scopes.includes(scope));
+}
+function requiredFeatures(metrics) {
+    const features = metrics.flatMap((metric) => metric.requires === undefined ? [] : [metric.requires]);
+    return [...new Set(features)];
+}
+function createTenantMetricQuery(metric, now) {
+    return defineQueryHandler({
+        name: metric.id,
+        description: metric.description,
+        schema: tenantPayloadSchema,
+        access: { roles: access.admin },
+        handler: (query, ctx) => runMetric(ctx.db, metric, {
+            range: query.payload.range,
+            timeZone: query.payload.timeZone,
+            now: now(),
+            // ctx.db already reads own-tenant + SYSTEM reference rows; this narrows to own-tenant only.
+            scopeWhere: { tenantId: query.user.tenantId },
+        }),
+    });
+}
+function createSystemMetricQuery(metric, now) {
+    return defineQueryHandler({
+        name: metric.id,
+        description: metric.description,
+        schema: systemPayloadSchema,
+        access: { roles: access.systemAdmin },
+        handler: (query, ctx) => {
+            if (!ctx.systemDb) {
+                throw new InternalError({
+                    message: `${METRICS_SYSTEM_FEATURE}:query:${metric.id} requires ctx.systemDb — is r.systemScope() set?`,
+                });
+            }
+            const { tenantId } = query.payload;
+            if (tenantId !== undefined && !metricHasTenantColumn(metric)) {
+                throw new ValidationError({
+                    fields: [
+                        {
+                            path: "tenantId",
+                            code: "unsupported",
+                            i18nKey: "metrics.errors.tenantFilterUnsupported",
+                        },
+                    ],
+                });
+            }
+            const db = ctx.systemDb.acknowledgeCrossTenant(`${METRICS_SYSTEM_FEATURE}:${metric.id} — SystemAdmin platform-wide aggregate`);
+            return runMetric(db, metric, {
+                range: query.payload.range,
+                timeZone: query.payload.timeZone,
+                now: now(),
+                scopeWhere: tenantId === undefined ? {} : { tenantId },
+            });
+        },
+    });
+}
+export function createMetricsFeature(options) {
+    validateMetrics(options.metrics);
+    const metrics = metricsForScope(options.metrics, "tenant");
+    const now = options.now ?? defaultClock;
+    return defineFeature(METRICS_FEATURE, (r) => {
+        r.describe("Declarative tenant-scoped metrics: each metric declaration becomes an admin-only query that aggregates a read-model table for the caller's own tenant and returns the shape dashboard panels consume (stat value with period delta, time series, ranked rows).");
+        r.uiHints({
+            displayLabel: "Metrics · Tenant Dashboard Data",
+            category: "operations",
+            recommended: false,
+        });
+        for (const feature of requiredFeatures(metrics))
+            r.requires(feature);
+        for (const metric of metrics)
+            r.queryHandler(createTenantMetricQuery(metric, now));
+        r.translations({ keys: METRICS_I18N });
+    });
+}
+export function createSystemMetricsFeature(options) {
+    validateMetrics(options.metrics);
+    const metrics = metricsForScope(options.metrics, "system");
+    const now = options.now ?? defaultClock;
+    return defineFeature(METRICS_SYSTEM_FEATURE, (r) => {
+        r.describe("Declarative platform-wide metrics for SystemAdmin: each metric declaration becomes a query that aggregates a read-model table across all tenants (optionally narrowed to one tenant) and returns the shape dashboard panels consume.");
+        r.uiHints({
+            displayLabel: "Metrics · Platform Dashboard Data",
+            category: "operations",
+            recommended: false,
+        });
+        r.systemScope();
+        for (const feature of requiredFeatures(metrics))
+            r.requires(feature);
+        for (const metric of metrics)
+            r.queryHandler(createSystemMetricQuery(metric, now));
+        r.translations({ keys: METRICS_I18N });
+    });
+}

package/dist/metrics/i18n.d.ts

@@ -0,0 +1,5 @@
+type LocalizedString = {
+    readonly en: string;
+};
+export declare const METRICS_I18N: Readonly<Record<string, LocalizedString>>;
+export {};

package/dist/metrics/i18n.js

@@ -0,0 +1,16 @@
+export const METRICS_I18N = {
+    "metrics:jobStatus.queued": { en: "Queued" },
+    "metrics:jobStatus.running": { en: "Running" },
+    "metrics:jobStatus.completed": { en: "Completed" },
+    "metrics:jobStatus.failed": { en: "Failed" },
+    "metrics:deliveryStatus.queued": { en: "Queued" },
+    "metrics:deliveryStatus.sent": { en: "Sent" },
+    "metrics:deliveryStatus.failed": { en: "Failed" },
+    "metrics:deliveryStatus.skipped": { en: "Skipped" },
+    "metrics:deliveryChannel.inApp": { en: "In-app" },
+    "metrics:deliveryChannel.email": { en: "Email" },
+    "metrics:deliveryChannel.push": { en: "Push" },
+    "metrics.errors.tenantFilterUnsupported": {
+        en: "This metric's source has no tenant column, so it cannot be narrowed to one tenant.",
+    },
+};

package/dist/metrics/index.d.ts

@@ -0,0 +1,5 @@
+export { METRIC_RANGES, METRICS_FEATURE, METRICS_SYSTEM_FEATURE, type MetricRange, type MetricScope, metricQueryName, } from "./constants.js";
+export { activeTenantsMetric, activeUsersMetric, auditWritesMetric, DEFAULT_METRICS, deliveriesByChannelMetric, failedDeliveriesMetric, failedJobRunsMetric, jobRunsByStatusMetric, tenantJobFailuresMetric, } from "./default-metrics.js";
+export { createMetricsFeature, createSystemMetricsFeature } from "./feature.js";
+export { METRICS_I18N } from "./i18n.js";
+export { defineMetric, type MetricDefinition, type MetricPoint, type MetricResult, type MetricRow, type MetricSegment, type MetricSeries, type MetricsFeatureOptions, } from "./types.js";

package/dist/metrics/index.js

@@ -0,0 +1,6 @@
+// Public API of the metrics bundled-feature.
+export { METRIC_RANGES, METRICS_FEATURE, METRICS_SYSTEM_FEATURE, metricQueryName, } from "./constants.js";
+export { activeTenantsMetric, activeUsersMetric, auditWritesMetric, DEFAULT_METRICS, deliveriesByChannelMetric, failedDeliveriesMetric, failedJobRunsMetric, jobRunsByStatusMetric, tenantJobFailuresMetric, } from "./default-metrics.js";
+export { createMetricsFeature, createSystemMetricsFeature } from "./feature.js";
+export { METRICS_I18N } from "./i18n.js";
+export { defineMetric, } from "./types.js";

package/dist/metrics/types.d.ts

@@ -0,0 +1,70 @@
+import type { EntityTableMeta } from "@cosmicdrift/kumiko-framework/db";
+import type { AggregateMeasure, AggregateTimeBucket } from "@cosmicdrift/kumiko-types/aggregate-types";
+import type { SchemaTable } from "@cosmicdrift/kumiko-types/schema-table-types";
+import type { WhereObject } from "@cosmicdrift/kumiko-types/where-clause-types";
+import type { Temporal } from "temporal-polyfill";
+import type { MetricRange, MetricScope } from "./constants.js";
+export type MetricDefinition = {
+    readonly id: string;
+    readonly description: string;
+    readonly source: SchemaTable | EntityTableMeta;
+    /** Feature that owns the source table; becomes `r.requires(...)`. */
+    readonly requires?: string;
+    readonly measure: AggregateMeasure;
+    readonly where?: WhereObject;
+    /** timestamptz column; without it the metric is a snapshot with no window. */
+    readonly timeField?: string;
+    /** Fixed window, ignores the payload range. */
+    readonly window?: MetricRange;
+    /** "auto": 24h → hour, otherwise day. */
+    readonly bucket?: AggregateTimeBucket | "auto";
+    /** Default true; false skips the previous-period query (no delta), for measures the previous window cannot answer, e.g. overwritten lastSeenAt. */
+    readonly comparePrevious?: boolean;
+    readonly groupBy?: string;
+    /** Second dimension, becomes `rows[].segments`; only without bucket. */
+    readonly stackBy?: string;
+    /** Key value → i18n key, applied to groupBy and stackBy keys. */
+    readonly groupLabels?: Readonly<Record<string, string>>;
+    readonly scopes: readonly MetricScope[];
+};
+export declare function defineMetric(definition: MetricDefinition): MetricDefinition;
+export type MetricPoint = {
+    readonly atMs: number;
+    readonly value: number | null;
+};
+export type MetricSeries = {
+    readonly key: string;
+    readonly label: string;
+    readonly points: readonly MetricPoint[];
+};
+export type MetricSegment = {
+    readonly key: string;
+    readonly label: string;
+    readonly value: number;
+};
+export type MetricRow = {
+    readonly id: string;
+    readonly key: string;
+    readonly label: string;
+    readonly value: number;
+    readonly fraction: number;
+    readonly segments?: readonly MetricSegment[];
+};
+export type MetricDeltaDirection = "up" | "down";
+export type MetricResult = {
+    readonly value: number | null;
+    readonly previousValue: number | null;
+    readonly delta: string | null;
+    readonly deltaDirection: MetricDeltaDirection | null;
+    readonly windowStartMs: number | null;
+    readonly windowEndMs: number | null;
+    readonly points: readonly MetricPoint[];
+    readonly series: readonly MetricSeries[];
+    readonly rows: readonly MetricRow[];
+    readonly nextCursor: null;
+};
+export type MetricsFeatureOptions = {
+    readonly metrics: readonly MetricDefinition[];
+    /** Fixed clock for deterministic tests. */
+    readonly now?: () => Temporal.Instant;
+};

package/dist/metrics/types.js

@@ -0,0 +1,3 @@
+export function defineMetric(definition) {
+    return definition;
+}

package/dist/metrics/validate.d.ts

@@ -0,0 +1,3 @@
+import type { MetricDefinition } from "./types.js";
+export declare function metricHasTenantColumn(metric: MetricDefinition): boolean;
+export declare function validateMetrics(metrics: readonly MetricDefinition[]): void;

package/dist/metrics/validate.js

@@ -0,0 +1,74 @@
+import { extractTableInfo, isTimestamptzType } from "@cosmicdrift/kumiko-framework/bun-db";
+import { METRIC_RANGES } from "./constants.js";
+const KEBAB_ID = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
+const TENANT_ID_FIELD = "tenantId";
+export function metricHasTenantColumn(metric) {
+    return extractTableInfo(metric.source).hasColumn(TENANT_ID_FIELD);
+}
+export function validateMetrics(metrics) {
+    const seen = new Set();
+    for (const metric of metrics) {
+        if (seen.has(metric.id)) {
+            throw new Error(`metrics: duplicate metric id "${metric.id}"`);
+        }
+        seen.add(metric.id);
+        validateMetric(metric);
+    }
+}
+function validateMetric(metric) {
+    const fail = (reason) => {
+        throw new Error(`metrics: metric "${metric.id}" ${reason}`);
+    };
+    if (!KEBAB_ID.test(metric.id))
+        fail("has an id that is not kebab-case");
+    if (metric.scopes.length === 0)
+        fail("declares no scopes");
+    const info = extractTableInfo(metric.source);
+    validateColumns(metric, info, fail);
+    validateTimeSettings(metric, info, fail);
+    validateShape(metric, fail);
+    if (metric.scopes.includes("tenant") && !metricHasTenantColumn(metric)) {
+        fail(`has scope "tenant" but ${info.name} has no tenant_id column`);
+    }
+}
+function validateColumns(metric, info, fail) {
+    const requireColumn = (field, role) => {
+        if (!info.hasColumn(field))
+            fail(`${role} "${field}" is not a column of ${info.name}`);
+    };
+    if (metric.measure.fn !== "count")
+        requireColumn(metric.measure.field, "measure field");
+    for (const field of Object.keys(metric.where ?? {}))
+        requireColumn(field, "where field");
+    if (metric.groupBy !== undefined)
+        requireColumn(metric.groupBy, "groupBy field");
+    if (metric.stackBy !== undefined)
+        requireColumn(metric.stackBy, "stackBy field");
+    if (metric.timeField !== undefined)
+        requireColumn(metric.timeField, "timeField");
+}
+function validateTimeSettings(metric, info, fail) {
+    const { timeField } = metric;
+    if (timeField === undefined) {
+        if (metric.bucket !== undefined)
+            fail("sets bucket without timeField");
+        if (metric.window !== undefined)
+            fail("sets window without timeField");
+    }
+    else {
+        if (!isTimestamptzType(info.pgTypeOf(info.columnOf(timeField)))) {
+            fail(`timeField "${timeField}" is not a timestamptz column`);
+        }
+        if (metric.window !== undefined && !METRIC_RANGES.includes(metric.window)) {
+            fail(`has an unknown window "${metric.window}"`);
+        }
+    }
+}
+function validateShape(metric, fail) {
+    if (metric.stackBy !== undefined) {
+        if (metric.groupBy === undefined)
+            fail("sets stackBy without groupBy");
+        if (metric.bucket !== undefined)
+            fail("combines stackBy with bucket");
+    }
+}