@wtfalch/reporting 0.1.0

package/dist/reader.js

@@ -0,0 +1,40 @@
+import { and, desc, eq, lt, or } from 'drizzle-orm';
+import { reportingEvents } from './tables.js';
+/**
+ * Newest first, keyset-paged on `(occurred_at, id)`, which is the table's
+ * first index. Every filter is an equality on an indexed column. No
+ * permission is applied here: the host gates, and this returns rows as
+ * stored.
+ */
+export async function eventsPage(db, opts = {}) {
+    const limit = Math.max(1, Math.min(opts.limit ?? 50, 200));
+    const conditions = [];
+    if (opts.level)
+        conditions.push(eq(reportingEvents.level, opts.level));
+    if (opts.kindNs)
+        conditions.push(eq(reportingEvents.kindNs, opts.kindNs));
+    if (opts.tenantId)
+        conditions.push(eq(reportingEvents.tenantId, opts.tenantId));
+    if (opts.site)
+        conditions.push(eq(reportingEvents.site, opts.site));
+    if (opts.requestId)
+        conditions.push(eq(reportingEvents.requestId, opts.requestId));
+    if (opts.after) {
+        const { occurredAt, id } = opts.after;
+        const keyset = or(lt(reportingEvents.occurredAt, occurredAt), and(eq(reportingEvents.occurredAt, occurredAt), lt(reportingEvents.id, id)));
+        if (keyset)
+            conditions.push(keyset);
+    }
+    const rows = await db
+        .select()
+        .from(reportingEvents)
+        .where(conditions.length > 0 ? and(...conditions) : undefined)
+        .orderBy(desc(reportingEvents.occurredAt), desc(reportingEvents.id))
+        .limit(limit + 1);
+    const items = rows.slice(0, limit);
+    const last = items.at(-1);
+    return {
+        items,
+        next: rows.length > limit && last ? { occurredAt: last.occurredAt, id: last.id } : null,
+    };
+}

package/dist/schema.d.ts

@@ -0,0 +1,78 @@
+import { z } from 'zod';
+/**
+ * What a row may hold, refused in TypeScript before it is queued and again by
+ * the table's CHECKs. The two lists that matter for privacy, `BANNED_KEYS` and
+ * the flatness rule, are here and in `migrations/0001_reporting.sql`, and
+ * `schema.test.ts` reads the SQL to pin them equal.
+ */
+export declare const LEVELS: readonly ["info", "warn", "error", "alert"];
+export type Level = (typeof LEVELS)[number];
+export declare const ACTOR_CLASSES: readonly ["human", "api_key", "agent", "service"];
+export type ActorClass = (typeof ACTOR_CLASSES)[number];
+/** `namespace.name`: one dot, lower case, digits and underscores. */
+export declare const KIND_PATTERN: RegExp;
+export declare const SITE_PATTERN: RegExp;
+/**
+ * Keys a `data` object may not carry, because each names a person or a
+ * secret. A guardrail against the accidental case, not proof of absence: a
+ * string under any other key can still hold an address, and review is the
+ * third net.
+ */
+export declare const BANNED_KEYS: readonly ["email", "name", "display_name", "displayName", "password", "secret", "token", "authorization"];
+export declare const LIMITS: {
+    readonly message: 512;
+    readonly actorId: 256;
+    readonly requestId: 128;
+    readonly targetType: 64;
+    readonly targetId: 256;
+    readonly dataBytes: 16384;
+    readonly site: 64;
+};
+/** Flat, bounded, and free of the banned keys. Numbers must be finite: JSON has no NaN. */
+export declare const flatDataSchema: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>;
+export type FlatData = z.infer<typeof flatDataSchema>;
+export declare const actorSchema: z.ZodObject<{
+    class: z.ZodEnum<{
+        human: "human";
+        api_key: "api_key";
+        agent: "agent";
+        service: "service";
+    }>;
+    id: z.ZodString;
+}, z.core.$strict>;
+export type Actor = z.infer<typeof actorSchema>;
+export declare const targetSchema: z.ZodObject<{
+    type: z.ZodString;
+    id: z.ZodString;
+}, z.core.$strict>;
+/** What a caller hands `event()`. Everything else on the row is the writer's. */
+export declare const eventInputSchema: z.ZodObject<{
+    kind: z.ZodString;
+    message: z.ZodString;
+    level: z.ZodDefault<z.ZodEnum<{
+        info: "info";
+        warn: "warn";
+        error: "error";
+        alert: "alert";
+    }>>;
+    tenantId: z.ZodOptional<z.ZodNullable<z.ZodUUID>>;
+    actor: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        class: z.ZodEnum<{
+            human: "human";
+            api_key: "api_key";
+            agent: "agent";
+            service: "service";
+        }>;
+        id: z.ZodString;
+    }, z.core.$strict>>>;
+    requestId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    target: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        type: z.ZodString;
+        id: z.ZodString;
+    }, z.core.$strict>>>;
+    data: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>>;
+    occurredAt: z.ZodOptional<z.ZodDate>;
+}, z.core.$strict>;
+export type EventInput = z.input<typeof eventInputSchema>;
+export type ValidEvent = z.output<typeof eventInputSchema>;
+export declare const siteSchema: z.ZodString;

package/dist/schema.js

@@ -0,0 +1,80 @@
+import { z } from 'zod';
+/**
+ * What a row may hold, refused in TypeScript before it is queued and again by
+ * the table's CHECKs. The two lists that matter for privacy, `BANNED_KEYS` and
+ * the flatness rule, are here and in `migrations/0001_reporting.sql`, and
+ * `schema.test.ts` reads the SQL to pin them equal.
+ */
+export const LEVELS = ['info', 'warn', 'error', 'alert'];
+export const ACTOR_CLASSES = ['human', 'api_key', 'agent', 'service'];
+/** `namespace.name`: one dot, lower case, digits and underscores. */
+export const KIND_PATTERN = /^[a-z][a-z0-9_]*\.[a-z][a-z0-9_]*$/;
+export const SITE_PATTERN = /^[a-z][a-z0-9-]{0,63}$/;
+/**
+ * Keys a `data` object may not carry, because each names a person or a
+ * secret. A guardrail against the accidental case, not proof of absence: a
+ * string under any other key can still hold an address, and review is the
+ * third net.
+ */
+export const BANNED_KEYS = [
+    'email',
+    'name',
+    'display_name',
+    'displayName',
+    'password',
+    'secret',
+    'token',
+    'authorization',
+];
+export const LIMITS = {
+    message: 512,
+    actorId: 256,
+    requestId: 128,
+    targetType: 64,
+    targetId: 256,
+    dataBytes: 16384,
+    site: 64,
+};
+const scalar = z.union([z.string(), z.number(), z.boolean(), z.null()]);
+/** Flat, bounded, and free of the banned keys. Numbers must be finite: JSON has no NaN. */
+export const flatDataSchema = z.record(z.string(), scalar).superRefine((data, ctx) => {
+    for (const key of Object.keys(data)) {
+        if (BANNED_KEYS.includes(key)) {
+            ctx.addIssue({ code: 'custom', path: [key], message: `"${key}" may not be a data key` });
+        }
+        const value = data[key];
+        if (typeof value === 'number' && !Number.isFinite(value)) {
+            ctx.addIssue({ code: 'custom', path: [key], message: 'must be a finite number' });
+        }
+    }
+    if (Buffer.byteLength(JSON.stringify(data), 'utf8') > LIMITS.dataBytes) {
+        ctx.addIssue({
+            code: 'custom',
+            message: `must serialise to at most ${LIMITS.dataBytes} bytes`,
+        });
+    }
+});
+const bounded = (max) => z.string().min(1).max(max);
+export const actorSchema = z.strictObject({
+    class: z.enum(ACTOR_CLASSES),
+    id: bounded(LIMITS.actorId),
+});
+export const targetSchema = z.strictObject({
+    type: bounded(LIMITS.targetType),
+    id: bounded(LIMITS.targetId),
+});
+/** What a caller hands `event()`. Everything else on the row is the writer's. */
+export const eventInputSchema = z.strictObject({
+    kind: z.string().regex(KIND_PATTERN, 'a kind is namespace.name, lower case'),
+    message: bounded(LIMITS.message),
+    level: z.enum(LEVELS).default('info'),
+    tenantId: z.uuid().nullish(),
+    actor: actorSchema.nullish(),
+    requestId: bounded(LIMITS.requestId).nullish(),
+    target: targetSchema.nullish(),
+    data: flatDataSchema.default({}),
+    occurredAt: z.date().optional(),
+});
+export const siteSchema = z
+    .string()
+    .regex(SITE_PATTERN, 'a site id is lower case, digits and dashes');

package/dist/settings.d.ts

@@ -0,0 +1,16 @@
+import type { Actor, Db, Settings, SettingsChange } from './types.js';
+/**
+ * Operator-edited settings, one row per key, read by housekeeping on every
+ * run. Bounds are enforced here and again inside `reporting_prune_events`,
+ * whose clamp is what makes a setting safe to expose: the worst an edit can
+ * do is shorten history to a week.
+ */
+export declare const RETENTION_BOUNDS: {
+    readonly min: 7;
+    readonly max: 400;
+};
+export declare const SETTING_KEYS: (keyof Settings)[];
+export declare const DEFAULT_SETTINGS: Settings;
+export declare function getSettings(db: Db): Promise<Settings>;
+/** Validates every key, writes the changed ones in one transaction, returns before and after. Throws on an out-of-bounds value: the caller is a form. */
+export declare function setSettings(db: Db, patch: Partial<Settings>, by: Actor): Promise<SettingsChange>;

package/dist/settings.js

@@ -0,0 +1,71 @@
+import { sql } from 'drizzle-orm';
+import { z } from 'zod';
+import { reportingSettings } from './tables.js';
+/**
+ * Operator-edited settings, one row per key, read by housekeeping on every
+ * run. Bounds are enforced here and again inside `reporting_prune_events`,
+ * whose clamp is what makes a setting safe to expose: the worst an edit can
+ * do is shorten history to a week.
+ */
+export const RETENTION_BOUNDS = { min: 7, max: 400 };
+const DEFS = {
+    'events.retention_days': {
+        schema: z.number().int().min(RETENTION_BOUNDS.min).max(RETENTION_BOUNDS.max),
+        default: 30,
+    },
+};
+export const SETTING_KEYS = Object.keys(DEFS);
+export const DEFAULT_SETTINGS = Object.freeze({
+    'events.retention_days': DEFS['events.retention_days'].default,
+});
+function fromRows(rows) {
+    const out = { ...DEFAULT_SETTINGS };
+    for (const row of rows) {
+        const def = DEFS[row.key];
+        if (!def)
+            continue;
+        const parsed = def.schema.safeParse(row.value);
+        if (parsed.success)
+            out[row.key] = parsed.data;
+    }
+    return out;
+}
+export async function getSettings(db) {
+    const rows = await db
+        .select({ key: reportingSettings.key, value: reportingSettings.value })
+        .from(reportingSettings);
+    return fromRows(rows);
+}
+/** Validates every key, writes the changed ones in one transaction, returns before and after. Throws on an out-of-bounds value: the caller is a form. */
+export async function setSettings(db, patch, by) {
+    const entries = Object.entries(patch);
+    for (const [key, value] of entries) {
+        const def = DEFS[key];
+        if (!def)
+            throw new Error(`reporting.settings: unknown key "${key}"`);
+        const parsed = def.schema.safeParse(value);
+        if (!parsed.success) {
+            throw new Error(`reporting.settings: ${key} must be an integer between ${RETENTION_BOUNDS.min} and ${RETENTION_BOUNDS.max}`);
+        }
+    }
+    return db.transaction(async (tx) => {
+        const before = fromRows(await tx
+            .select({ key: reportingSettings.key, value: reportingSettings.value })
+            .from(reportingSettings));
+        const changed = [];
+        for (const [key, value] of entries) {
+            if (before[key] === value)
+                continue;
+            changed.push(key);
+            await tx
+                .insert(reportingSettings)
+                .values({ key, value, updatedBy: `${by.class}:${by.id}` })
+                .onConflictDoUpdate({
+                target: reportingSettings.key,
+                set: { value, updatedAt: sql `now()`, updatedBy: `${by.class}:${by.id}` },
+            });
+        }
+        const after = { ...before, ...Object.fromEntries(entries) };
+        return { before, after, by, changed };
+    });
+}