@dappermountain/payload-plugin-achievements 0.2.6 → 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/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"}

package/dist/collections/hooks/preventCatalogDelete.js

@@ -61,7 +61,8 @@ export function preventCatalogDelete(args) {
                 parts.push(`${logs.totalDocs} log row(s)`);
             const rules = await countMatchingLeaves({
                 req,
-                match: (rule) => rule.type === 'event-count' && relationId(rule.eventType) === id,
+                match: (rule) => (rule.type === 'event-count' || rule.type === 'elapsed-since') &&
+                    relationId(rule.eventType) === id,
             });
             if (rules > 0)
                 parts.push(`${rules} rule(s)`);
@@ -75,6 +76,14 @@ export function preventCatalogDelete(args) {
             });
             if (logs.totalDocs > 0)
                 parts.push(`${logs.totalDocs} log row(s)`);
+            const balances = await req.payload.count({
+                collection: collectionOf('metricBalances'),
+                overrideAccess: true,
+                req,
+                where: { metric: { equals: id } },
+            });
+            if (balances.totalDocs > 0)
+                parts.push(`${balances.totalDocs} balance row(s)`);
             const rules = await countMatchingLeaves({
                 req,
                 match: (rule) => rule.type === 'metric-minimum' && relationId(rule.metric) === id,

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/collections/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAA;AAyB/C,qEAAqE;AACrE,wBAAgB,2BAA2B,IAAI,gBAAgB,EAAE,CAMhE"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/collections/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAA;AA2B/C,qEAAqE;AACrE,wBAAgB,2BAA2B,IAAI,gBAAgB,EAAE,CAMhE"}

package/dist/collections/index.js

@@ -5,11 +5,13 @@ import { buildAchievementsCollection } from './Achievements/index.js';
 import { buildEventTypesCollection } from './EventTypes/index.js';
 import { buildGrantsCollection } from './Grants/index.js';
 import { buildLogsCollection } from './Logs/index.js';
+import { buildMetricBalancesCollection } from './MetricBalances/index.js';
 import { buildMetricsCollection } from './Metrics/index.js';
 import { buildTierRequestsCollection } from './TierRequests/index.js';
 import { buildTiersCollection } from './Tiers/index.js';
 const builders = {
     metrics: buildMetricsCollection,
+    metricBalances: buildMetricBalancesCollection,
     eventTypes: buildEventTypesCollection,
     tiers: buildTiersCollection,
     achievements: buildAchievementsCollection,

package/dist/collections/slugs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"slugs.d.ts","sourceRoot":"","sources":["../../src/collections/slugs.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,wBAAwB,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAA;AAErF;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB,gBAAgB,CAAA;AAEtD;;;GAGG;AACH,eAAO,MAAM,6BAA6B,EAAE,MAAM,CAAC,wBAAwB,EAAE,MAAM,CASlF,CAAA;AAED,eAAO,MAAM,mBAAmB,iBAAiB,CAAA;AAEjD;;;;GAIG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,GAAE,wBAA6B,GACrC,MAAM,CAAC,wBAAwB,EAAE,MAAM,CAAC,CAkB1C;AAED,wBAAgB,iBAAiB,CAAC,OAAO,GAAE,wBAA6B,GAAG,MAAM,GAAG,KAAK,CAMxF"}
+{"version":3,"file":"slugs.d.ts","sourceRoot":"","sources":["../../src/collections/slugs.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,wBAAwB,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAA;AAErF;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB,gBAAgB,CAAA;AAEtD;;;GAGG;AACH,eAAO,MAAM,6BAA6B,EAAE,MAAM,CAAC,wBAAwB,EAAE,MAAM,CAUlF,CAAA;AAED,eAAO,MAAM,mBAAmB,iBAAiB,CAAA;AAEjD;;;;GAIG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,GAAE,wBAA6B,GACrC,MAAM,CAAC,wBAAwB,EAAE,MAAM,CAAC,CAkB1C;AAED,wBAAgB,iBAAiB,CAAC,OAAO,GAAE,wBAA6B,GAAG,MAAM,GAAG,KAAK,CAMxF"}

package/dist/collections/slugs.js

@@ -18,6 +18,7 @@ export const DEFAULT_COLLECTION_BASE_SLUGS = {
     logs: 'logs',
     eventTypes: 'event-types',
     metrics: 'metrics',
+    metricBalances: 'metric-balances',
 };
 export const DEFAULT_ADMIN_GROUP = 'Achievements';
 /**

package/dist/defaults.d.ts

@@ -2,9 +2,11 @@ import type { AchievementPluginOptions } from './types.js';
 import { resolveCollectionSlugs } from './collections/slugs.js';
 export declare const DEFAULT_USERS_COLLECTION = "users";
 export declare const DEFAULT_ME_ENDPOINT_PATH = "/achievements/me";
+export declare const DEFAULT_LEADERBOARD_ENDPOINT_PATH = "/achievements/leaderboard";
 export declare const DEFAULT_RECONCILE_ENDPOINT_PATH = "/achievements/reconcile";
 export type ResolvedAchievementOptions = Omit<AchievementPluginOptions, 'users' | 'endpoints'> & {
     enabled: boolean;
+    seedSystemCatalog: boolean;
     usersCollectionSlug: string;
     users: {
         includeJoins: boolean;
@@ -15,10 +17,12 @@ export type ResolvedAchievementOptions = Omit<AchievementPluginOptions, 'users'
     adminGroup: string | false;
     endpoints: {
         me: string | false;
+        leaderboard: string | false;
         reconcile: string | false;
     };
 };
 export declare function resolveMeEndpointPath(me?: string | false): string | false;
+export declare function resolveLeaderboardEndpointPath(path?: string | false): string | false;
 export declare function resolveReconcileEndpointPath(path?: string | false): string | false;
 export declare function resolveOptions(options?: AchievementPluginOptions): ResolvedAchievementOptions;
 //# sourceMappingURL=defaults.d.ts.map

package/dist/defaults.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"defaults.d.ts","sourceRoot":"","sources":["../src/defaults.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,YAAY,CAAA;AAC1D,OAAO,EAEL,sBAAsB,EACvB,MAAM,wBAAwB,CAAA;AAE/B,eAAO,MAAM,wBAAwB,UAAU,CAAA;AAC/C,eAAO,MAAM,wBAAwB,qBAAqB,CAAA;AAC1D,eAAO,MAAM,+BAA+B,4BAA4B,CAAA;AAExE,MAAM,MAAM,0BAA0B,GAAG,IAAI,CAAC,wBAAwB,EAAE,OAAO,GAAG,WAAW,CAAC,GAAG;IAC/F,OAAO,EAAE,OAAO,CAAA;IAChB,mBAAmB,EAAE,MAAM,CAAA;IAC3B,KAAK,EAAE;QAAE,YAAY,EAAE,OAAO,CAAA;KAAE,CAAA;IAChC,+DAA+D;IAC/D,eAAe,EAAE,UAAU,CAAC,OAAO,sBAAsB,CAAC,CAAA;IAC1D,oEAAoE;IACpE,UAAU,EAAE,MAAM,GAAG,KAAK,CAAA;IAC1B,SAAS,EAAE;QAAE,EAAE,EAAE,MAAM,GAAG,KAAK,CAAC;QAAC,SAAS,EAAE,MAAM,GAAG,KAAK,CAAA;KAAE,CAAA;CAC7D,CAAA;AAQD,wBAAgB,qBAAqB,CAAC,EAAE,CAAC,EAAE,MAAM,GAAG,KAAK,GAAG,MAAM,GAAG,KAAK,CAIzE;AAED,wBAAgB,4BAA4B,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,KAAK,GAAG,MAAM,GAAG,KAAK,CAIlF;AAED,wBAAgB,cAAc,CAAC,OAAO,GAAE,wBAA6B,GAAG,0BAA0B,CAejG"}
+{"version":3,"file":"defaults.d.ts","sourceRoot":"","sources":["../src/defaults.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,YAAY,CAAA;AAC1D,OAAO,EAEL,sBAAsB,EACvB,MAAM,wBAAwB,CAAA;AAE/B,eAAO,MAAM,wBAAwB,UAAU,CAAA;AAC/C,eAAO,MAAM,wBAAwB,qBAAqB,CAAA;AAC1D,eAAO,MAAM,iCAAiC,8BAA8B,CAAA;AAC5E,eAAO,MAAM,+BAA+B,4BAA4B,CAAA;AAExE,MAAM,MAAM,0BAA0B,GAAG,IAAI,CAAC,wBAAwB,EAAE,OAAO,GAAG,WAAW,CAAC,GAAG;IAC/F,OAAO,EAAE,OAAO,CAAA;IAChB,iBAAiB,EAAE,OAAO,CAAA;IAC1B,mBAAmB,EAAE,MAAM,CAAA;IAC3B,KAAK,EAAE;QAAE,YAAY,EAAE,OAAO,CAAA;KAAE,CAAA;IAChC,+DAA+D;IAC/D,eAAe,EAAE,UAAU,CAAC,OAAO,sBAAsB,CAAC,CAAA;IAC1D,oEAAoE;IACpE,UAAU,EAAE,MAAM,GAAG,KAAK,CAAA;IAC1B,SAAS,EAAE;QAAE,EAAE,EAAE,MAAM,GAAG,KAAK,CAAC;QAAC,WAAW,EAAE,MAAM,GAAG,KAAK,CAAC;QAAC,SAAS,EAAE,MAAM,GAAG,KAAK,CAAA;KAAE,CAAA;CAC1F,CAAA;AAQD,wBAAgB,qBAAqB,CAAC,EAAE,CAAC,EAAE,MAAM,GAAG,KAAK,GAAG,MAAM,GAAG,KAAK,CAIzE;AAED,wBAAgB,8BAA8B,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,KAAK,GAAG,MAAM,GAAG,KAAK,CAIpF;AAED,wBAAgB,4BAA4B,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,KAAK,GAAG,MAAM,GAAG,KAAK,CAIlF;AAED,wBAAgB,cAAc,CAAC,OAAO,GAAE,wBAA6B,GAAG,0BAA0B,CAiBjG"}

package/dist/defaults.js

@@ -1,6 +1,7 @@
 import { resolveAdminGroup, resolveCollectionSlugs, } from './collections/slugs.js';
 export const DEFAULT_USERS_COLLECTION = 'users';
 export const DEFAULT_ME_ENDPOINT_PATH = '/achievements/me';
+export const DEFAULT_LEADERBOARD_ENDPOINT_PATH = '/achievements/leaderboard';
 export const DEFAULT_RECONCILE_ENDPOINT_PATH = '/achievements/reconcile';
 function normalizeEndpointPath(path, fallback) {
     const trimmed = path.trim();
@@ -15,6 +16,13 @@ export function resolveMeEndpointPath(me) {
         return DEFAULT_ME_ENDPOINT_PATH;
     return normalizeEndpointPath(me, DEFAULT_ME_ENDPOINT_PATH);
 }
+export function resolveLeaderboardEndpointPath(path) {
+    if (path === false)
+        return false;
+    if (path == null)
+        return DEFAULT_LEADERBOARD_ENDPOINT_PATH;
+    return normalizeEndpointPath(path, DEFAULT_LEADERBOARD_ENDPOINT_PATH);
+}
 export function resolveReconcileEndpointPath(path) {
     if (path === false)
         return false;
@@ -26,6 +34,7 @@ export function resolveOptions(options = {}) {
     return {
         ...options,
         enabled: options.enabled !== false,
+        seedSystemCatalog: options.seedSystemCatalog !== false,
         usersCollectionSlug: options.usersCollectionSlug ?? DEFAULT_USERS_COLLECTION,
         users: {
             includeJoins: options.users?.includeJoins !== false,
@@ -34,6 +43,7 @@ export function resolveOptions(options = {}) {
         adminGroup: resolveAdminGroup(options),
         endpoints: {
             me: resolveMeEndpointPath(options.endpoints?.me),
+            leaderboard: resolveLeaderboardEndpointPath(options.endpoints?.leaderboard),
             reconcile: resolveReconcileEndpointPath(options.endpoints?.reconcile),
         },
     };

package/dist/endpoints/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/endpoints/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAA;AAEvC,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,gBAAgB,CAAA;AAIhE,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,0BAA0B,GAAG,QAAQ,EAAE,CASzF"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/endpoints/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAA;AAEvC,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,gBAAgB,CAAA;AAKhE,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,0BAA0B,GAAG,QAAQ,EAAE,CAYzF"}

package/dist/endpoints/index.js

@@ -1,3 +1,4 @@
+import { buildLeaderboardEndpoint } from './leaderboard.js';
 import { buildMeEndpoint } from './me.js';
 import { buildReconcileEndpoint } from './reconcile.js';
 export function buildAchievementEndpoints(options) {
@@ -5,6 +6,9 @@ export function buildAchievementEndpoints(options) {
     if (options.endpoints.me !== false) {
         endpoints.push(buildMeEndpoint(options.endpoints.me));
     }
+    if (options.endpoints.leaderboard !== false) {
+        endpoints.push(buildLeaderboardEndpoint(options.endpoints.leaderboard));
+    }
     if (options.endpoints.reconcile !== false) {
         endpoints.push(buildReconcileEndpoint(options.endpoints.reconcile));
     }

package/dist/endpoints/leaderboard.d.ts

@@ -0,0 +1,6 @@
+import type { Endpoint } from 'payload';
+/**
+ * `GET` ranked stored-metric balances. Query: `metric` (required), optional `scope` / `limit` / `page`.
+ */
+export declare function buildLeaderboardEndpoint(path: string): Endpoint;
+//# sourceMappingURL=leaderboard.d.ts.map

package/dist/endpoints/leaderboard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"leaderboard.d.ts","sourceRoot":"","sources":["../../src/endpoints/leaderboard.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAkB,MAAM,SAAS,CAAA;AAsBvD;;GAEG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,CAuC/D"}