@dappermountain/payload-plugin-achievements 0.2.5 → 0.2.7

package/README.md

@@ -79,7 +79,8 @@ Slugs are prefixed with `achievement-` by default so they don’t collide with y
 
 | Config key | Default slug | Purpose |
 | --- | --- | --- |
-| `metrics` | `achievement-metrics` | Named scores (points, streaks, …). Totals are derived by summing `metric.delta` logs. |
+| `metrics` | `achievement-metrics` | Named numbers: **stored** (score totals) or **computed** (e.g. elapsed days). |
+| `metricBalances` | `achievement-metric-balances` | Projection of stored metric totals per user (+ scope) for fast reads / leaderboards. |
 | `eventTypes` | `achievement-event-types` | Kinds of log entries you can count or require. |
 | `tiers` | `achievement-tiers` | Ordered ladder steps with unlock rules. |
 | `achievements` | `achievement-definitions` | Things a user can earn (with eligibility / completion rules). |
@@ -106,7 +107,7 @@ Unlock (tiers), eligibility, and completion (achievements) share the same rule t
 
 - Top-level empty list → everyone passes
 - Nested groups → AND (“all of these”) or OR (“any of these”)
-- Built-in leaves → `tier-at-least`, `achievement-complete`, `metric-minimum`, `event-count`
+- Built-in leaves → `tier-at-least`, `achievement-complete`, `metric-minimum`, `event-count`, `elapsed-since`
 - Custom leaves → register via `extensions.ruleTypes`
 
 **Current tier** is computed by walking tiers in `rank` order and evaluating each tier’s unlock rules (`resolveCurrentTier`). Tiers with **`requiresReview`** only become current after an **approved tier request**. **Next-tier fill** uses fractional progress on the same trees (`resolveTierProgress` / `evaluateRuleProgress`):
@@ -116,9 +117,17 @@ Unlock (tiers), eligibility, and completion (achievements) share the same rule t
 | AND | Equal average of *requirement* children |
 | OR | Best child (max) |
 | `tier-at-least` | Gate — skipped in AND averages |
-| `event-count` / `metric-minimum` | Fraction of the target |
+| `event-count` / `metric-minimum` / `elapsed-since` | Fraction of the target |
 | `achievement-complete` | `1` if granted; otherwise rolls up that achievement’s completion (or eligibility) rules |
 
+**`elapsed-since`** — time since an anchor ≥ amount (unit: `days` | `hours` | `minutes`). Built-in anchors: user `createdAt`, or earliest log of an event type (`since: 'first-event'`). Hosts register more anchors via `extensions.metricAnchors` (same keys work on computed metrics).
+
+**Stored vs computed metrics** — `kind: stored` (default) totals live in `achievement-metric-balances`, updated by `recordMetricChange` (log + balance dual-write). Logs remain the audit/rebuild source; reconcile backfills balances. `kind: computed` + `compute: elapsed` exposes a live number (e.g. days since an anchor); use `metric-minimum` against it. System seed only creates stored `points` — product computed metrics (e.g. `days`) are host-seeded after registering anchors.
+
+**Leaderboards** — `getMetricLeaderboard` / `GET /api/achievements/leaderboard?metric=points` ranks stored balances (authenticated). Disable with `endpoints.leaderboard: false`.
+
+**System catalog** — by default the plugin runs `seedAchievementCatalog` on Payload `onInit` (opt out with `seedSystemCatalog: false`). Hosts still seed product catalog + locales via `seedAchievements`.
+
 **Eligibility rules** gate who may request an achievement. **Completion rules** define what a composed achievement is made of. When `requiresReview` is false and completion rules pass, the parent can auto-grant. Cycles in nested achievement graphs are ignored.
 
 ### Access model
@@ -159,8 +168,11 @@ achievementPlugin({
     overrides?: Partial<Record<AchievementCollectionKey, AchievementCollectionOverride>>
   }
   users?: { includeJoins?: boolean }
-  endpoints?: { me?: string | false }
-  extensions?: { ruleTypes?: AchievementRuleType[] }
+  endpoints?: { me?: string | false; leaderboard?: string | false; reconcile?: string | false }
+  extensions?: {
+    ruleTypes?: AchievementRuleType[]
+    metricAnchors?: Record<string, AchievementMetricAnchor>
+  }
 })
 ```
 
@@ -169,10 +181,12 @@ achievementPlugin({
 | Option | Default | Notes |
 | --- | --- | --- |
 | `enabled` | `true` | Set `false` to leave the plugin installed but inactive (no collections / endpoints merged). |
+| `seedSystemCatalog` | `true` | On `onInit`, upsert system metrics + event types (`points`, `metric.delta`, …). |
 | `usersCollectionSlug` | `'users'` | Users collection the plugin relates to (grants, requests, joins). |
 | `canReview` | _(denied)_ | **Important.** Without this, users cannot manage catalogs or approve requests. Receives `(user, scopeId)` where `scopeId` may be `null`. |
 | `scope` | _(none)_ | Multi-tenant hook-up. `collection` is the relation target (e.g. `'tenants'`). `relationField` defaults to `'scope'`. Adds an optional scope field across plugin collections. |
 | `mediaCollection` | _(none)_ | When set (e.g. `'media'`), tiers get an optional upload field for ladder badge images. Icon string keys still work without this. |
+| `extensions.metricAnchors` | _(none)_ | Named `(ctx) => Date | null` resolvers for computed elapsed metrics / `elapsed-since`. Keys appear in Admin `since` selects. |
 
 ### `collections`
 
@@ -217,17 +231,25 @@ achievementPlugin({
 | Option | Default | Notes |
 | --- | --- | --- |
 | `me` | `'/achievements/me'` | Registers `GET /api/achievements/me` for the signed-in user’s grants snapshot (+ derived tiers and lean requests). Pass `false` to skip. Having review access does **not** widen this endpoint to other users. |
+| `leaderboard` | `'/achievements/leaderboard'` | Registers `GET /api/achievements/leaderboard?metric=<slug>` for authenticated users (stored metrics only). Pass `false` to skip. |
+| `reconcile` | `'/achievements/reconcile'` | Registers `POST /api/achievements/reconcile` for reviewers. Pass `false` to skip. |
 
-Query params: `scope`, `limit`, `page`, `requestsLimit`.
+Query params (`me`): `scope`, `limit`, `page`, `requestsLimit`. Leaderboard: `metric` (required), `scope`, `limit`, `page`.
 
-### `extensions.ruleTypes`
+### `extensions.ruleTypes` / `metricAnchors`
 
-Register custom rule evaluators merged with the built-ins:
+Register custom rule evaluators and/or date anchors:
 
 ```ts
 achievementPlugin({
   canReview,
   extensions: {
+    metricAnchors: {
+      'membership-granted': async ({ payload, userId, scopeId }) => {
+        // return a Date from host data, or null
+        return null
+      },
+    },
     ruleTypes: [
       {
         type: 'host.custom-check',
@@ -251,6 +273,8 @@ Use these from hooks, jobs, and trusted endpoints — not from the public client
 import {
   recordLog,
   recordMetricChange,
+  getMetricLeaderboard,
+  resolveMetricValue,
   grantAchievement,
   reconcileProgression,
   reconcileUserProgression,
@@ -263,6 +287,7 @@ import {
 
 await recordLog({ payload, userId, scopeId, type: 'host.custom-kind', actorId })
 await recordMetricChange({ payload, userId, scopeId, metric: 'points', change: 10 })
+const board = await getMetricLeaderboard({ payload, metric: 'points', scopeId, limit: 20 })
 const tier = await resolveCurrentTier({ payload, userId, scopeId })
 
 // Repair users whose grants predate side-effect hooks (idempotent)
@@ -306,6 +331,7 @@ Turning **Requires review** off on a definition or tier **approves pending reque
 | Goal | Request |
 | --- | --- |
 | Current user snapshot | `GET /api/achievements/me?scope=<scopeId>&limit=10&page=1` |
+| Stored metric leaderboard | `GET /api/achievements/leaderboard?metric=points&scope=<scopeId>&limit=20&page=1` |
 | Repair progression | `POST /api/achievements/reconcile` (reviewer; optional `{ userId, scopeId, achievementId\|achievementSlug, tierId\|tierSlug, limit }`) |
 | List grants | `GET /api/achievement-grants?where[user][equals]=<userId>` |
 | Log history | `GET /api/achievement-logs?where[user][equals]=<userId>` |

package/dist/admin/LucideIconField.d.ts

@@ -1,6 +1,6 @@
 import type { TextFieldClientComponent } from 'payload';
 /**
- * Searchable Lucide icon picker. Stores the kebab-case Lucide name (e.g. `sparkles`).
+ * Emoji-picker style Lucide field: searchable icon grid, stores kebab-case names.
  */
 export declare const LucideIconField: TextFieldClientComponent;
 //# sourceMappingURL=LucideIconField.d.ts.map

package/dist/admin/LucideIconField.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"LucideIconField.d.ts","sourceRoot":"","sources":["../../src/admin/LucideIconField.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,wBAAwB,EAAgB,MAAM,SAAS,CAAA;AA4BrE;;GAEG;AACH,eAAO,MAAM,eAAe,EAAE,wBA4D7B,CAAA"}
+{"version":3,"file":"LucideIconField.d.ts","sourceRoot":"","sources":["../../src/admin/LucideIconField.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,SAAS,CAAA;AAoCvD;;GAEG;AACH,eAAO,MAAM,eAAe,EAAE,wBAsO7B,CAAA"}

package/dist/admin/LucideIconField.js

@@ -1,8 +1,8 @@
 'use client';
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { FieldDescription, FieldError, FieldLabel, SelectInput, useField } from '@payloadcms/ui';
+import { FieldDescription, FieldError, FieldLabel, useField } from '@payloadcms/ui';
 import { icons } from 'lucide-react';
-import { useMemo } from 'react';
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 function toKebabCase(pascal) {
     return pascal
         .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
@@ -16,15 +16,17 @@ function toPascalCase(kebab) {
         .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
         .join('');
 }
-const ICON_OPTIONS = Object.keys(icons)
+const ALL_ICONS = Object.keys(icons)
     .filter((key) => /^[A-Z]/.test(key))
-    .map((pascal) => {
-    const value = toKebabCase(pascal);
-    return { label: value, value };
-})
-    .sort((a, b) => a.value.localeCompare(b.value));
+    .map((pascal) => ({
+    name: toKebabCase(pascal),
+    Icon: icons[pascal],
+}))
+    .sort((a, b) => a.name.localeCompare(b.name));
+const MAX_VISIBLE = 180;
+const CELL = 36;
 /**
- * Searchable Lucide icon picker. Stores the kebab-case Lucide name (e.g. `sparkles`).
+ * Emoji-picker style Lucide field: searchable icon grid, stores kebab-case names.
  */
 export const LucideIconField = (props) => {
     const { field, path: pathFromProps, readOnly } = props;
@@ -33,24 +35,137 @@ export const LucideIconField = (props) => {
         path,
     });
     const selected = typeof value === 'string' && value.length > 0 ? value : undefined;
-    const PreviewIcon = selected
+    const SelectedIcon = selected
         ? icons[toPascalCase(selected)]
         : undefined;
-    const options = useMemo(() => ICON_OPTIONS, []);
-    return (_jsxs("div", { className: "field-type", children: [_jsx(FieldLabel, { label: field?.label ?? 'Icon', path: path, required: Boolean(field?.required) }), _jsxs("div", { style: { alignItems: 'center', display: 'flex', gap: '0.75rem' }, children: [_jsx("div", { "aria-hidden": true, style: {
+    const [open, setOpen] = useState(false);
+    const [query, setQuery] = useState('');
+    const rootRef = useRef(null);
+    const searchRef = useRef(null);
+    const filtered = useMemo(() => {
+        const q = query.trim().toLowerCase();
+        const list = q
+            ? ALL_ICONS.filter((entry) => entry.name.includes(q))
+            : ALL_ICONS;
+        return list.slice(0, MAX_VISIBLE);
+    }, [query]);
+    const totalMatches = useMemo(() => {
+        const q = query.trim().toLowerCase();
+        if (!q)
+            return ALL_ICONS.length;
+        return ALL_ICONS.filter((entry) => entry.name.includes(q)).length;
+    }, [query]);
+    useEffect(() => {
+        if (!open)
+            return;
+        const onPointerDown = (event) => {
+            if (!rootRef.current?.contains(event.target)) {
+                setOpen(false);
+            }
+        };
+        const onKeyDown = (event) => {
+            if (event.key === 'Escape')
+                setOpen(false);
+        };
+        document.addEventListener('mousedown', onPointerDown);
+        document.addEventListener('keydown', onKeyDown);
+        queueMicrotask(() => searchRef.current?.focus());
+        return () => {
+            document.removeEventListener('mousedown', onPointerDown);
+            document.removeEventListener('keydown', onKeyDown);
+        };
+    }, [open]);
+    const pick = useCallback((name) => {
+        setValue(name);
+        setOpen(false);
+        setQuery('');
+    }, [setValue]);
+    const clear = useCallback(() => {
+        setValue(null);
+        setQuery('');
+    }, [setValue]);
+    return (_jsxs("div", { className: "field-type", ref: rootRef, children: [_jsx(FieldLabel, { label: field?.label ?? 'Icon', path: path, required: Boolean(field?.required) }), _jsxs("div", { style: { alignItems: 'center', display: 'flex', gap: '0.5rem', position: 'relative' }, children: [_jsxs("button", { "aria-expanded": open, "aria-haspopup": "dialog", disabled: Boolean(readOnly), onClick: () => setOpen((prev) => !prev), style: {
                             alignItems: 'center',
+                            background: 'var(--theme-input-bg)',
                             border: '1px solid var(--theme-elevation-150)',
-                            borderRadius: 6,
-                            display: 'flex',
-                            flexShrink: 0,
+                            borderRadius: 'var(--style-radius-s, 4px)',
+                            color: 'var(--theme-text)',
+                            cursor: readOnly ? 'default' : 'pointer',
+                            display: 'inline-flex',
+                            gap: '0.5rem',
+                            minHeight: 40,
+                            minWidth: 160,
+                            padding: '0 0.75rem',
+                        }, type: "button", children: [_jsx("span", { "aria-hidden": true, style: {
+                                    alignItems: 'center',
+                                    display: 'inline-flex',
+                                    height: 22,
+                                    justifyContent: 'center',
+                                    width: 22,
+                                }, children: SelectedIcon ? (_jsx(SelectedIcon, { size: 18 })) : (_jsx("span", { style: { color: 'var(--theme-elevation-400)', fontSize: 12 }, children: "\u2014" })) }), _jsx("span", { style: { fontSize: 13, opacity: selected ? 1 : 0.55 }, children: selected ?? 'Choose icon…' })] }), selected && !readOnly ? (_jsx("button", { onClick: clear, style: {
+                            background: 'transparent',
+                            border: '1px solid var(--theme-elevation-150)',
+                            borderRadius: 'var(--style-radius-s, 4px)',
+                            color: 'var(--theme-elevation-600)',
+                            cursor: 'pointer',
+                            fontSize: 12,
                             height: 40,
-                            justifyContent: 'center',
-                            width: 40,
-                        }, children: PreviewIcon ? (_jsx(PreviewIcon, { size: 20 })) : (_jsx("span", { style: { color: 'var(--theme-elevation-400)', fontSize: 12 }, children: "\u2014" })) }), _jsx("div", { style: { flex: 1, minWidth: 0 }, children: _jsx(SelectInput, { isClearable: true, name: path, onChange: (option) => {
-                                if (Array.isArray(option)) {
-                                    setValue(option[0]?.value ?? null);
-                                    return;
-                                }
-                                setValue(option?.value ?? null);
-                            }, options: options, path: path, readOnly: Boolean(readOnly), value: selected }) })] }), _jsx(FieldDescription, { description: field?.admin?.description, path: path }), _jsx(FieldError, { message: errorMessage, path: path, showError: showError })] }));
+                            padding: '0 0.65rem',
+                        }, type: "button", children: "Clear" })) : null, open && !readOnly ? (_jsxs("div", { role: "dialog", style: {
+                            background: 'var(--theme-elevation-0)',
+                            border: '1px solid var(--theme-elevation-150)',
+                            borderRadius: 'var(--style-radius-m, 6px)',
+                            boxShadow: '0 8px 28px rgba(0,0,0,0.18)',
+                            display: 'flex',
+                            flexDirection: 'column',
+                            left: 0,
+                            maxWidth: 'min(360px, 100vw)',
+                            padding: '0.65rem',
+                            position: 'absolute',
+                            top: 'calc(100% + 6px)',
+                            width: 360,
+                            zIndex: 40,
+                        }, children: [_jsx("input", { "aria-label": "Search Lucide icons", onChange: (event) => setQuery(event.target.value), placeholder: "Search icons\u2026", ref: searchRef, style: {
+                                    background: 'var(--theme-input-bg)',
+                                    border: '1px solid var(--theme-elevation-150)',
+                                    borderRadius: 'var(--style-radius-s, 4px)',
+                                    color: 'var(--theme-text)',
+                                    fontSize: 13,
+                                    marginBottom: '0.5rem',
+                                    padding: '0.45rem 0.6rem',
+                                    width: '100%',
+                                }, type: "search", value: query }), _jsx("div", { style: {
+                                    display: 'grid',
+                                    gap: 4,
+                                    gridTemplateColumns: `repeat(auto-fill, minmax(${CELL}px, 1fr))`,
+                                    maxHeight: 260,
+                                    overflowY: 'auto',
+                                    paddingBottom: 4,
+                                }, children: filtered.map(({ name, Icon }) => {
+                                    const isActive = name === selected;
+                                    return (_jsx("button", { onClick: () => pick(name), style: {
+                                            alignItems: 'center',
+                                            aspectRatio: '1',
+                                            background: isActive
+                                                ? 'var(--theme-success-100, var(--theme-elevation-100))'
+                                                : 'transparent',
+                                            border: isActive
+                                                ? '1px solid var(--theme-success-500, var(--theme-elevation-400))'
+                                                : '1px solid transparent',
+                                            borderRadius: 6,
+                                            color: 'var(--theme-text)',
+                                            cursor: 'pointer',
+                                            display: 'inline-flex',
+                                            justifyContent: 'center',
+                                            padding: 0,
+                                        }, title: name, type: "button", children: _jsx(Icon, { size: 18 }) }, name));
+                                }) }), _jsx("div", { style: {
+                                    color: 'var(--theme-elevation-500)',
+                                    fontSize: 11,
+                                    marginTop: 6,
+                                }, children: totalMatches === 0
+                                    ? 'No icons match.'
+                                    : totalMatches > MAX_VISIBLE
+                                        ? `Showing ${MAX_VISIBLE} of ${totalMatches} — refine search`
+                                        : `${totalMatches} icon${totalMatches === 1 ? '' : 's'}` })] })) : null] }), _jsx(FieldDescription, { description: field?.admin?.description, path: path }), _jsx(FieldError, { message: errorMessage, path: path, showError: showError })] }));
 };

package/dist/catalog.d.ts

@@ -15,6 +15,7 @@ export declare const ENGINE_EVENT_TYPES: readonly [{
 export declare const ENGINE_METRICS: readonly [{
     readonly slug: "points";
     readonly name: "Points";
+    readonly kind: "stored";
 }];
 export type EngineEventTypeSlug = (typeof ENGINE_EVENT_TYPES)[number]['slug'];
 export type EngineMetricSlug = (typeof ENGINE_METRICS)[number]['slug'];

package/dist/catalog.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"catalog.d.ts","sourceRoot":"","sources":["../src/catalog.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;EAKrB,CAAA;AAEV,eAAO,MAAM,cAAc;;;EAAgD,CAAA;AAE3E,MAAM,MAAM,mBAAmB,GAAG,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,CAAA;AAC7E,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,CAAA;AAEtE,eAAO,MAAM,+BAA+B,EAAE,gBAA2B,CAAA;AAEzE,+DAA+D;AAC/D,eAAO,MAAM,0BAA0B,UAAkC,CAAA"}
+{"version":3,"file":"catalog.d.ts","sourceRoot":"","sources":["../src/catalog.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;EAKrB,CAAA;AAEV,eAAO,MAAM,cAAc;;;;EAAyE,CAAA;AAEpG,MAAM,MAAM,mBAAmB,GAAG,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,CAAA;AAC7E,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,CAAA;AAEtE,eAAO,MAAM,+BAA+B,EAAE,gBAA2B,CAAA;AAEzE,+DAA+D;AAC/D,eAAO,MAAM,0BAA0B,UAAkC,CAAA"}

package/dist/catalog.js

@@ -4,7 +4,7 @@ export const ENGINE_EVENT_TYPES = [
     { slug: 'metric.delta', name: 'Metric delta', requiresMetric: true },
     { slug: 'tier.changed', name: 'Tier changed' },
 ];
-export const ENGINE_METRICS = [{ slug: 'points', name: 'Points' }];
+export const ENGINE_METRICS = [{ slug: 'points', name: 'Points', kind: 'stored' }];
 export const DEFAULT_ACHIEVEMENT_METRIC_SLUG = 'points';
 /** @deprecated Use {@link DEFAULT_ACHIEVEMENT_METRIC_SLUG}. */
 export const DEFAULT_ACHIEVEMENT_METRIC = DEFAULT_ACHIEVEMENT_METRIC_SLUG;

package/dist/cli/reconcile.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"reconcile.d.ts","sourceRoot":"","sources":["../../src/cli/reconcile.ts"],"names":[],"mappings":"AAAA,OAAO,EAAc,KAAK,eAAe,EAAE,MAAM,SAAS,CAAA;AAE1D,OAAO,EAEL,KAAK,wBAAwB,EAC7B,KAAK,0BAA0B,EAChC,MAAM,sCAAsC,CAAA;AAE7C,MAAM,MAAM,mBAAmB,GAAG,IAAI,CAAC,wBAAwB,EAAE,SAAS,GAAG,KAAK,CAAC,CAAA;AA2BnF,sFAAsF;AACtF,wBAAgB,qBAAqB,CAAC,IAAI,GAAE,MAAM,EAA0B,GAAG,mBAAmB,CAUjG;AAED,wBAAgB,qBAAqB,IAAI,IAAI,CAc5C;AAED;;;GAGG;AACH,wBAAsB,eAAe,CAAC,IAAI,EAAE;IAC1C,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC,CAAA;IAClD,IAAI,CAAC,EAAE,MAAM,EAAE,CAAA;IACf,OAAO,CAAC,EAAE,mBAAmB,CAAA;IAC7B,kFAAkF;IAClF,IAAI,CAAC,EAAE,OAAO,CAAA;CACf,GAAG,OAAO,CAAC,0BAA0B,CAAC,CA2BtC"}
+{"version":3,"file":"reconcile.d.ts","sourceRoot":"","sources":["../../src/cli/reconcile.ts"],"names":[],"mappings":"AAAA,OAAO,EAAc,KAAK,eAAe,EAAE,MAAM,SAAS,CAAA;AAE1D,OAAO,EAEL,KAAK,wBAAwB,EAC7B,KAAK,0BAA0B,EAChC,MAAM,sCAAsC,CAAA;AAE7C,MAAM,MAAM,mBAAmB,GAAG,IAAI,CAAC,wBAAwB,EAAE,SAAS,GAAG,KAAK,CAAC,CAAA;AA2BnF,sFAAsF;AACtF,wBAAgB,qBAAqB,CAAC,IAAI,GAAE,MAAM,EAA0B,GAAG,mBAAmB,CAUjG;AAED,wBAAgB,qBAAqB,IAAI,IAAI,CAc5C;AAED;;;GAGG;AACH,wBAAsB,eAAe,CAAC,IAAI,EAAE;IAC1C,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC,CAAA;IAClD,IAAI,CAAC,EAAE,MAAM,EAAE,CAAA;IACf,OAAO,CAAC,EAAE,mBAAmB,CAAA;IAC7B,kFAAkF;IAClF,IAAI,CAAC,EAAE,OAAO,CAAA;CACf,GAAG,OAAO,CAAC,0BAA0B,CAAC,CA4BtC"}

package/dist/cli/reconcile.js

@@ -70,6 +70,7 @@ export async function runReconcileCli(args) {
             achievementRequestsEnsured: 0,
             tierRequestsEnsured: 0,
             tierLogsWritten: 0,
+            metricBalancesRebuilt: 0,
         };
     }
     const filters = args.filters ?? parseReconcileCliArgs(argv);

package/dist/collections/MetricBalances/access/index.d.ts

@@ -0,0 +1,4 @@
+import type { CollectionConfig } from 'payload';
+/** Projection rows — writes only via trusted helpers (`overrideAccess`). */
+export declare const access: NonNullable<CollectionConfig['access']>;
+//# sourceMappingURL=index.d.ts.map

package/dist/collections/MetricBalances/access/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/collections/MetricBalances/access/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAA;AAK/C,4EAA4E;AAC5E,eAAO,MAAM,MAAM,EAAE,WAAW,CAAC,gBAAgB,CAAC,QAAQ,CAAC,CAK1D,CAAA"}

package/dist/collections/MetricBalances/access/index.js

@@ -0,0 +1,9 @@
+import { requireOne } from '../../../access/index.js';
+import { isReviewer } from '../../../access/roles/index.js';
+/** Projection rows — writes only via trusted helpers (`overrideAccess`). */
+export const access = {
+    read: requireOne(isReviewer('metricBalances')),
+    create: () => false,
+    update: () => false,
+    delete: requireOne(isReviewer('metricBalances')),
+};

package/dist/collections/MetricBalances/hooks/index.d.ts

@@ -0,0 +1,3 @@
+import type { CollectionConfig } from 'payload';
+export declare const hooks: CollectionConfig['hooks'];
+//# sourceMappingURL=index.d.ts.map

package/dist/collections/MetricBalances/hooks/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/collections/MetricBalances/hooks/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAA;AAE/C,eAAO,MAAM,KAAK,EAAE,gBAAgB,CAAC,OAAO,CAAM,CAAA"}

package/dist/collections/MetricBalances/hooks/index.js

@@ -0,0 +1 @@
+export const hooks = {};

package/dist/collections/MetricBalances/index.d.ts

@@ -0,0 +1,3 @@
+import type { CollectionConfig } from 'payload';
+export declare function buildMetricBalancesCollection(): CollectionConfig;
+//# sourceMappingURL=index.d.ts.map

package/dist/collections/MetricBalances/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/collections/MetricBalances/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAA;AAa/C,wBAAgB,6BAA6B,IAAI,gBAAgB,CA4ChE"}

package/dist/collections/MetricBalances/index.js

@@ -0,0 +1,48 @@
+import { collectionAdmin, collectionOf, columnsWithOptionalScope, optionalFields, slugOf, } from '../helpers.js';
+import { scopeField, userField } from '../fields/index.js';
+import { access } from './access/index.js';
+import { hooks } from './hooks/index.js';
+export function buildMetricBalancesCollection() {
+    return {
+        slug: slugOf('metricBalances'),
+        access: { ...access },
+        hooks,
+        admin: collectionAdmin({
+            useAsTitle: 'key',
+            defaultColumns: columnsWithOptionalScope(['metric', 'user', 'value', 'scope', 'updatedAt']),
+            description: 'Stored metric totals per user (and scope). Updated by recordMetricChange; repair with reconcile. Not for computed metrics.',
+        }),
+        fields: [
+            userField(),
+            ...optionalFields(scopeField()),
+            {
+                name: 'metric',
+                type: 'relationship',
+                relationTo: collectionOf('metrics'),
+                required: true,
+                index: true,
+            },
+            {
+                name: 'value',
+                type: 'number',
+                required: true,
+                defaultValue: 0,
+                index: true,
+                admin: {
+                    description: 'Current total (sum of metric.delta changes).',
+                },
+            },
+            {
+                name: 'key',
+                type: 'text',
+                required: true,
+                unique: true,
+                index: true,
+                admin: {
+                    readOnly: true,
+                    description: 'Stable unique key: user:scope:metric.',
+                },
+            },
+        ],
+    };
+}

package/dist/collections/Metrics/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/collections/Metrics/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAA;AAO/C,wBAAgB,sBAAsB,IAAI,gBAAgB,CA8BzD"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/collections/Metrics/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAA;AAS/C,wBAAgB,sBAAsB,IAAI,gBAAgB,CA2FzD"}

package/dist/collections/Metrics/index.js

@@ -1,5 +1,7 @@
-import { collectionAdmin, columnsWithOptionalScope, optionalFields, slugOf } from '../helpers.js';
+import { collectionAdmin, collectionOf, columnsWithOptionalScope, optionalFields, slugOf } from '../helpers.js';
 import { localizedNameField, scopeField } from '../fields/index.js';
+import { catalogFilterOptions } from '../fields/catalogFilter.js';
+import { elapsedSinceSelectOptions } from '../../extensions/elapsedSinceOptions.js';
 import { access } from './access/index.js';
 import { hooks } from './hooks/index.js';
 export function buildMetricsCollection() {
@@ -9,8 +11,8 @@ export function buildMetricsCollection() {
         hooks,
         admin: collectionAdmin({
             useAsTitle: 'name',
-            defaultColumns: columnsWithOptionalScope(['name', 'slug', 'system', 'scope']),
-            description: 'Scores and totals you track for someone — like points or a streak.',
+            defaultColumns: columnsWithOptionalScope(['name', 'slug', 'kind', 'system', 'scope']),
+            description: 'Named numbers. Stored metrics are score totals from log deltas; computed metrics are derived at evaluation time.',
         }),
         fields: [
             ...optionalFields(scopeField()),
@@ -21,6 +23,65 @@ export function buildMetricsCollection() {
                     { name: 'slug', type: 'text', required: true, unique: true, index: true, admin: { width: '50%' } },
                 ],
             },
+            {
+                name: 'kind',
+                type: 'select',
+                required: true,
+                defaultValue: 'stored',
+                options: [
+                    { label: 'Stored (log deltas)', value: 'stored' },
+                    { label: 'Computed', value: 'computed' },
+                ],
+                admin: {
+                    description: 'Stored = sum of metric.delta logs (via balances). Computed = derived value.',
+                },
+            },
+            {
+                name: 'compute',
+                type: 'select',
+                defaultValue: 'elapsed',
+                options: [{ label: 'Elapsed time', value: 'elapsed' }],
+                admin: {
+                    condition: (_, sibling) => sibling?.kind === 'computed',
+                    description: 'How this number is derived.',
+                },
+            },
+            {
+                name: 'unit',
+                type: 'select',
+                defaultValue: 'days',
+                options: [
+                    { label: 'Days', value: 'days' },
+                    { label: 'Hours', value: 'hours' },
+                    { label: 'Minutes', value: 'minutes' },
+                ],
+                admin: {
+                    condition: (_, sibling) => sibling?.kind === 'computed' && sibling?.compute === 'elapsed',
+                    description: 'Unit of the exposed number (e.g. whole days since the anchor).',
+                },
+            },
+            {
+                name: 'since',
+                type: 'select',
+                defaultValue: 'user-created-at',
+                options: elapsedSinceSelectOptions(),
+                admin: {
+                    condition: (_, sibling) => sibling?.kind === 'computed' && sibling?.compute === 'elapsed',
+                    description: 'Which timestamp starts the clock.',
+                },
+            },
+            {
+                name: 'eventType',
+                type: 'relationship',
+                relationTo: collectionOf('eventTypes'),
+                filterOptions: catalogFilterOptions,
+                admin: {
+                    condition: (_, sibling) => sibling?.kind === 'computed' &&
+                        sibling?.compute === 'elapsed' &&
+                        sibling?.since === 'first-event',
+                    description: 'Event type whose first log starts the clock.',
+                },
+            },
             {
                 name: 'system',
                 type: 'checkbox',

package/dist/collections/fields/ruleFields.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ruleFields.d.ts","sourceRoot":"","sources":["../../../src/collections/fields/ruleFields.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAA;AAqGpC;;GAEG;AACH,wBAAgB,mBAAmB,IAAI,KAAK,EAAE,CAqB7C;AAED,mDAAmD;AACnD,wBAAgB,kBAAkB,IAAI,KAAK,EAAE,CAE5C"}
+{"version":3,"file":"ruleFields.d.ts","sourceRoot":"","sources":["../../../src/collections/fields/ruleFields.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAA;AAkJpC;;GAEG;AACH,wBAAgB,mBAAmB,IAAI,KAAK,EAAE,CAqB7C;AAED,mDAAmD;AACnD,wBAAgB,kBAAkB,IAAI,KAAK,EAAE,CAE5C"}

package/dist/collections/fields/ruleFields.js

@@ -1,5 +1,6 @@
 import { catalogFilterOptions } from './catalogFilter.js';
 import { collectionOf } from '../helpers.js';
+import { elapsedSinceSelectOptions } from '../../extensions/elapsedSinceOptions.js';
 function combinatorField(visibleWhenGroup) {
     return {
         name: 'combinator',
@@ -25,6 +26,7 @@ function ruleTypeSelect(includeGroup) {
             { label: 'Achievement complete', value: 'achievement-complete' },
             { label: 'Metric minimum', value: 'metric-minimum' },
             { label: 'Event count', value: 'event-count' },
+            { label: 'Elapsed since', value: 'elapsed-since' },
             ...(includeGroup ? [{ label: 'Group', value: 'group' }] : []),
         ],
     };
@@ -75,8 +77,9 @@ function ruleParamFields() {
             relationTo: collectionOf('eventTypes'),
             filterOptions: catalogFilterOptions,
             admin: {
-                condition: (_, sibling) => sibling?.type === 'event-count',
-                description: 'Which event type to count.',
+                condition: (_, sibling) => sibling?.type === 'event-count' ||
+                    (sibling?.type === 'elapsed-since' && sibling?.since === 'first-event'),
+                description: 'Event type to count, or (for elapsed since) the type whose first log starts the clock.',
             },
         },
         {
@@ -87,6 +90,46 @@ function ruleParamFields() {
                 description: 'How many times it needs to have happened.',
             },
         },
+        {
+            name: 'since',
+            type: 'select',
+            defaultValue: 'user-created-at',
+            options: elapsedSinceSelectOptions(),
+            admin: {
+                condition: (_, sibling) => sibling?.type === 'elapsed-since',
+                description: 'Which timestamp starts the clock.',
+            },
+        },
+        {
+            type: 'row',
+            admin: {
+                condition: (_, sibling) => sibling?.type === 'elapsed-since',
+            },
+            fields: [
+                {
+                    name: 'amount',
+                    type: 'number',
+                    admin: {
+                        width: '50%',
+                        description: 'How much time must pass.',
+                    },
+                },
+                {
+                    name: 'unit',
+                    type: 'select',
+                    defaultValue: 'days',
+                    options: [
+                        { label: 'Days', value: 'days' },
+                        { label: 'Hours', value: 'hours' },
+                        { label: 'Minutes', value: 'minutes' },
+                    ],
+                    admin: {
+                        width: '50%',
+                        description: 'Unit for the amount.',
+                    },
+                },
+            ],
+        },
     ];
 }
 function buildRuleLeafFields() {

package/dist/collections/hooks/preventCatalogDelete.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"preventCatalogDelete.d.ts","sourceRoot":"","sources":["../../../src/collections/hooks/preventCatalogDelete.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,SAAS,CAAA;AA6CzD,wBAAgB,oBAAoB,CAAC,IAAI,EAAE;IACzC,IAAI,EAAE,WAAW,GAAG,QAAQ,CAAA;CAC7B,GAAG,0BAA0B,CAqD7B"}
+{"version":3,"file":"preventCatalogDelete.d.ts","sourceRoot":"","sources":["../../../src/collections/hooks/preventCatalogDelete.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,SAAS,CAAA;AA6CzD,wBAAgB,oBAAoB,CAAC,IAAI,EAAE;IACzC,IAAI,EAAE,WAAW,GAAG,QAAQ,CAAA;CAC7B,GAAG,0BAA0B,CA+D7B"}