@dappermountain/payload-plugin-achievements 0.2.5 → 0.2.7

package/dist/services/achievement/getMetricLeaderboard.js

@@ -0,0 +1,62 @@
+import { APIError } from 'payload';
+import { collectionOf } from '../../collections/helpers.js';
+import { getAchievementOptions } from '../../options-store.js';
+import { loadMetricDoc } from './resolveMetricValue.js';
+import { relationId } from './relationId.js';
+/**
+ * Ranked stored-metric balances for a scope (or unscoped board when `scopeId` is null).
+ */
+export async function getMetricLeaderboard(args) {
+    const metric = await loadMetricDoc({
+        payload: args.payload,
+        req: args.req,
+        metric: args.metric,
+    });
+    if (!metric) {
+        throw new APIError('Metric not found.', 404);
+    }
+    if ((metric.kind ?? 'stored') === 'computed') {
+        throw new APIError('Leaderboards are only available for stored metrics.', 400);
+    }
+    const limit = Math.min(Math.max(args.limit ?? 20, 1), 100);
+    const page = Math.max(args.page ?? 1, 1);
+    const scopeId = args.scopeId ?? null;
+    const scopeConfigured = Boolean(getAchievementOptions().scope?.collection);
+    const clauses = [{ metric: { equals: metric.id } }];
+    if (scopeId) {
+        clauses.push({ scope: { equals: scopeId } });
+    }
+    else if (scopeConfigured) {
+        clauses.push({
+            or: [{ scope: { exists: false } }, { scope: { equals: null } }],
+        });
+    }
+    const result = await args.payload.find({
+        collection: collectionOf('metricBalances'),
+        depth: 0,
+        limit,
+        page,
+        overrideAccess: true,
+        req: args.req,
+        sort: '-value,id',
+        where: { and: clauses },
+    });
+    const offset = (page - 1) * limit;
+    const docs = result.docs.map((doc, index) => {
+        const row = doc;
+        return {
+            user: relationId(row.user) ?? String(row.user ?? ''),
+            value: typeof row.value === 'number' && Number.isFinite(row.value) ? row.value : 0,
+            rank: offset + index + 1,
+        };
+    });
+    return {
+        docs,
+        totalDocs: result.totalDocs,
+        page: result.page ?? page,
+        limit,
+        totalPages: result.totalPages ?? Math.max(1, Math.ceil(result.totalDocs / limit)),
+        metric: { id: metric.id, slug: metric.slug },
+        scopeId,
+    };
+}

package/dist/services/achievement/index.d.ts

@@ -3,6 +3,11 @@ export type { RuleGroup, AchievementCompleteRef } from './evaluateRules.js';
 export { buildCatalogProgressGroups } from './buildCatalogProgressGroups.js';
 export type { CatalogProgressGroup, CatalogProgressItem } from './buildCatalogProgressGroups.js';
 export { getUserProgress } from './getUserProgress.js';
+export { getMetricLeaderboard } from './getMetricLeaderboard.js';
+export type { MetricLeaderboardResult, MetricLeaderboardRow } from './getMetricLeaderboard.js';
+export { applyMetricBalanceDelta, findMetricBalance, metricBalanceKey, rebuildMetricBalance, rebuildMetricBalancesForUser, } from './metricBalances.js';
+export { resolveMetricValue, loadMetricDoc } from './resolveMetricValue.js';
+export { resolveElapsedAnchor } from './resolveElapsedAnchor.js';
 export { recordEvent, recordLog, recordMetricChange, syncTierChangedLog } from './recordEvent.js';
 export { resolveCurrentTier } from './resolveCurrentTier.js';
 export type { ResolvedTier } from './resolveCurrentTier.js';

package/dist/services/achievement/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/services/achievement/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,8BAA8B,EAAE,MAAM,oBAAoB,CAAA;AAC5H,YAAY,EAAE,SAAS,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAA;AAC3E,OAAO,EAAE,0BAA0B,EAAE,MAAM,iCAAiC,CAAA;AAC5E,YAAY,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,MAAM,iCAAiC,CAAA;AAChG,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AACtD,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAA;AACjG,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAA;AAC5D,YAAY,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAA;AAC3D,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAA;AAC9D,YAAY,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAA;AAClE,OAAO,EAAE,gBAAgB,EAAE,wBAAwB,EAAE,MAAM,+BAA+B,CAAA;AAC1F,OAAO,EAAE,wBAAwB,EAAE,MAAM,+BAA+B,CAAA;AACxE,OAAO,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAA;AACxE,OAAO,EAAE,wBAAwB,EAAE,MAAM,uBAAuB,CAAA;AAChE,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAA;AAC1D,OAAO,EAAE,oBAAoB,EAAE,wBAAwB,EAAE,MAAM,gBAAgB,CAAA;AAC/E,YAAY,EAAE,wBAAwB,EAAE,0BAA0B,EAAE,MAAM,gBAAgB,CAAA;AAC1F,OAAO,EACL,wBAAwB,EACxB,gCAAgC,EAChC,yBAAyB,GAC1B,MAAM,wBAAwB,CAAA;AAC/B,YAAY,EAAE,uBAAuB,EAAE,MAAM,wBAAwB,CAAA;AACrE,OAAO,EACL,UAAU,EACV,iBAAiB,EACjB,cAAc,GACf,MAAM,cAAc,CAAA;AACrB,YAAY,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/services/achievement/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,8BAA8B,EAAE,MAAM,oBAAoB,CAAA;AAC5H,YAAY,EAAE,SAAS,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAA;AAC3E,OAAO,EAAE,0BAA0B,EAAE,MAAM,iCAAiC,CAAA;AAC5E,YAAY,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,MAAM,iCAAiC,CAAA;AAChG,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AACtD,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAA;AAChE,YAAY,EAAE,uBAAuB,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAA;AAC9F,OAAO,EACL,uBAAuB,EACvB,iBAAiB,EACjB,gBAAgB,EAChB,oBAAoB,EACpB,4BAA4B,GAC7B,MAAM,qBAAqB,CAAA;AAC5B,OAAO,EAAE,kBAAkB,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAA;AAC3E,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAA;AAChE,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAA;AACjG,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAA;AAC5D,YAAY,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAA;AAC3D,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAA;AAC9D,YAAY,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAA;AAClE,OAAO,EAAE,gBAAgB,EAAE,wBAAwB,EAAE,MAAM,+BAA+B,CAAA;AAC1F,OAAO,EAAE,wBAAwB,EAAE,MAAM,+BAA+B,CAAA;AACxE,OAAO,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAA;AACxE,OAAO,EAAE,wBAAwB,EAAE,MAAM,uBAAuB,CAAA;AAChE,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAA;AAC1D,OAAO,EAAE,oBAAoB,EAAE,wBAAwB,EAAE,MAAM,gBAAgB,CAAA;AAC/E,YAAY,EAAE,wBAAwB,EAAE,0BAA0B,EAAE,MAAM,gBAAgB,CAAA;AAC1F,OAAO,EACL,wBAAwB,EACxB,gCAAgC,EAChC,yBAAyB,GAC1B,MAAM,wBAAwB,CAAA;AAC/B,YAAY,EAAE,uBAAuB,EAAE,MAAM,wBAAwB,CAAA;AACrE,OAAO,EACL,UAAU,EACV,iBAAiB,EACjB,cAAc,GACf,MAAM,cAAc,CAAA;AACrB,YAAY,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAA"}

package/dist/services/achievement/index.js

@@ -1,6 +1,10 @@
 export { evaluateRules, evaluateRuleProgress, normalizeRuleGroup, collectAchievementCompleteRefs } from './evaluateRules.js';
 export { buildCatalogProgressGroups } from './buildCatalogProgressGroups.js';
 export { getUserProgress } from './getUserProgress.js';
+export { getMetricLeaderboard } from './getMetricLeaderboard.js';
+export { applyMetricBalanceDelta, findMetricBalance, metricBalanceKey, rebuildMetricBalance, rebuildMetricBalancesForUser, } from './metricBalances.js';
+export { resolveMetricValue, loadMetricDoc } from './resolveMetricValue.js';
+export { resolveElapsedAnchor } from './resolveElapsedAnchor.js';
 export { recordEvent, recordLog, recordMetricChange, syncTierChangedLog } from './recordEvent.js';
 export { resolveCurrentTier } from './resolveCurrentTier.js';
 export { resolveTierProgress } from './resolveTierProgress.js';

package/dist/services/achievement/metricBalances.d.ts

@@ -0,0 +1,42 @@
+import type { Payload, PayloadRequest } from 'payload';
+export declare function metricBalanceKey(userId: string, scopeId: string | null, metricId: string): string;
+export declare function findMetricBalance(args: {
+    payload: Payload;
+    req?: PayloadRequest;
+    userId: string;
+    scopeId: string | null;
+    metricId: string;
+}): Promise<{
+    id: string;
+    value: number;
+} | null>;
+export declare function applyMetricBalanceDelta(args: {
+    payload: Payload;
+    req?: PayloadRequest;
+    userId: string;
+    scopeId: string | null;
+    metricId: string;
+    change: number;
+}): Promise<{
+    id: string;
+    value: number;
+}>;
+/** Sum metric.delta log changes and upsert the balance projection. */
+export declare function rebuildMetricBalance(args: {
+    payload: Payload;
+    req?: PayloadRequest;
+    userId: string;
+    scopeId?: string | null;
+    metricId: string;
+}): Promise<{
+    id: string;
+    value: number;
+}>;
+/** Rebuild balances for every distinct metric seen in this user’s metric.delta logs. */
+export declare function rebuildMetricBalancesForUser(args: {
+    payload: Payload;
+    req?: PayloadRequest;
+    userId: string;
+    scopeId?: string | null;
+}): Promise<number>;
+//# sourceMappingURL=metricBalances.d.ts.map

package/dist/services/achievement/metricBalances.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metricBalances.d.ts","sourceRoot":"","sources":["../../../src/services/achievement/metricBalances.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,SAAS,CAAA;AAMtD,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAEjG;AAED,wBAAsB,iBAAiB,CAAC,IAAI,EAAE;IAC5C,OAAO,EAAE,OAAO,CAAA;IAChB,GAAG,CAAC,EAAE,cAAc,CAAA;IACpB,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB,QAAQ,EAAE,MAAM,CAAA;CACjB,GAAG,OAAO,CAAC;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAAC,CAehD;AAED,wBAAsB,uBAAuB,CAAC,IAAI,EAAE;IAClD,OAAO,EAAE,OAAO,CAAA;IAChB,GAAG,CAAC,EAAE,cAAc,CAAA;IACpB,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB,QAAQ,EAAE,MAAM,CAAA;IAChB,MAAM,EAAE,MAAM,CAAA;CACf,GAAG,OAAO,CAAC;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,CAgCzC;AAED,sEAAsE;AACtE,wBAAsB,oBAAoB,CAAC,IAAI,EAAE;IAC/C,OAAO,EAAE,OAAO,CAAA;IAChB,GAAG,CAAC,EAAE,cAAc,CAAA;IACpB,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACvB,QAAQ,EAAE,MAAM,CAAA;CACjB,GAAG,OAAO,CAAC;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,CAoDzC;AAED,wFAAwF;AACxF,wBAAsB,4BAA4B,CAAC,IAAI,EAAE;IACvD,OAAO,EAAE,OAAO,CAAA;IAChB,GAAG,CAAC,EAAE,cAAc,CAAA;IACpB,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CACxB,GAAG,OAAO,CAAC,MAAM,CAAC,CAgClB"}

package/dist/services/achievement/metricBalances.js

@@ -0,0 +1,137 @@
+import { collectionOf } from '../../collections/helpers.js';
+import { relationId } from './relationId.js';
+import { userScopeWhere } from './where.js';
+export function metricBalanceKey(userId, scopeId, metricId) {
+    return `${userId}:${scopeId ?? ''}:${metricId}`;
+}
+export async function findMetricBalance(args) {
+    const key = metricBalanceKey(args.userId, args.scopeId, args.metricId);
+    const found = await args.payload.find({
+        collection: collectionOf('metricBalances'),
+        depth: 0,
+        limit: 1,
+        overrideAccess: true,
+        req: args.req,
+        where: { key: { equals: key } },
+    });
+    const doc = found.docs[0];
+    const id = relationId(doc);
+    if (!id)
+        return null;
+    const value = typeof doc?.value === 'number' && Number.isFinite(doc.value) ? doc.value : 0;
+    return { id, value };
+}
+export async function applyMetricBalanceDelta(args) {
+    const existing = await findMetricBalance(args);
+    const nextValue = (existing?.value ?? 0) + args.change;
+    const key = metricBalanceKey(args.userId, args.scopeId, args.metricId);
+    if (existing) {
+        const updated = await args.payload.update({
+            collection: collectionOf('metricBalances'),
+            id: existing.id,
+            data: { value: nextValue },
+            overrideAccess: true,
+            req: args.req,
+        });
+        return { id: existing.id, value: typeof updated.value === 'number' ? updated.value : nextValue };
+    }
+    const created = await args.payload.create({
+        collection: collectionOf('metricBalances'),
+        data: {
+            user: args.userId,
+            scope: args.scopeId ?? undefined,
+            metric: args.metricId,
+            value: nextValue,
+            key,
+        },
+        overrideAccess: true,
+        req: args.req,
+    });
+    return {
+        id: String(created.id),
+        value: typeof created.value === 'number' ? created.value : nextValue,
+    };
+}
+/** Sum metric.delta log changes and upsert the balance projection. */
+export async function rebuildMetricBalance(args) {
+    const scopeId = args.scopeId ?? null;
+    const logs = await args.payload.find({
+        collection: collectionOf('logs'),
+        depth: 0,
+        limit: 10_000,
+        pagination: false,
+        overrideAccess: true,
+        req: args.req,
+        where: {
+            and: [userScopeWhere(args.userId, scopeId), { metric: { equals: args.metricId } }],
+        },
+    });
+    const value = logs.docs.reduce((sum, doc) => {
+        const change = doc.change;
+        return sum + (typeof change === 'number' && Number.isFinite(change) ? change : 0);
+    }, 0);
+    const existing = await findMetricBalance({
+        payload: args.payload,
+        req: args.req,
+        userId: args.userId,
+        scopeId,
+        metricId: args.metricId,
+    });
+    const key = metricBalanceKey(args.userId, scopeId, args.metricId);
+    if (existing) {
+        await args.payload.update({
+            collection: collectionOf('metricBalances'),
+            id: existing.id,
+            data: { value },
+            overrideAccess: true,
+            req: args.req,
+        });
+        return { id: existing.id, value };
+    }
+    const created = await args.payload.create({
+        collection: collectionOf('metricBalances'),
+        data: {
+            user: args.userId,
+            scope: scopeId ?? undefined,
+            metric: args.metricId,
+            value,
+            key,
+        },
+        overrideAccess: true,
+        req: args.req,
+    });
+    return { id: String(created.id), value };
+}
+/** Rebuild balances for every distinct metric seen in this user’s metric.delta logs. */
+export async function rebuildMetricBalancesForUser(args) {
+    const scopeId = args.scopeId ?? null;
+    const logs = await args.payload.find({
+        collection: collectionOf('logs'),
+        depth: 0,
+        limit: 10_000,
+        pagination: false,
+        overrideAccess: true,
+        req: args.req,
+        where: {
+            and: [userScopeWhere(args.userId, scopeId), { metric: { exists: true } }],
+        },
+    });
+    const metricIds = new Set();
+    for (const doc of logs.docs) {
+        const id = relationId(doc.metric);
+        if (id)
+            metricIds.add(id);
+    }
+    let rebuilt = 0;
+    for (const metricId of metricIds) {
+        await rebuildMetricBalance({
+            payload: args.payload,
+            req: args.req,
+            userId: args.userId,
+            scopeId,
+            metricId,
+        });
+        rebuilt += 1;
+    }
+    return rebuilt;
+}

package/dist/services/achievement/reconcile.d.ts

@@ -6,6 +6,7 @@ export type ReconcileProgressionResult = {
     achievementRequestsEnsured: number;
     tierRequestsEnsured: number;
     tierLogsWritten: number;
+    metricBalancesRebuilt: number;
 };
 export type ReconcileProgressionArgs = {
     payload: Payload;

package/dist/services/achievement/reconcile.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"reconcile.d.ts","sourceRoot":"","sources":["../../../src/services/achievement/reconcile.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,cAAc,EAAS,MAAM,SAAS,CAAA;AAa7D,MAAM,MAAM,0BAA0B,GAAG;IACvC,YAAY,EAAE,MAAM,CAAA;IACpB,qBAAqB,EAAE,MAAM,CAAA;IAC7B,iBAAiB,EAAE,MAAM,CAAA;IACzB,0BAA0B,EAAE,MAAM,CAAA;IAClC,mBAAmB,EAAE,MAAM,CAAA;IAC3B,eAAe,EAAE,MAAM,CAAA;CACxB,CAAA;AAED,MAAM,MAAM,wBAAwB,GAAG;IACrC,OAAO,EAAE,OAAO,CAAA;IAChB,GAAG,CAAC,EAAE,cAAc,CAAA;IACpB,2BAA2B;IAC3B,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACvB,8EAA8E;IAC9E,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC7B,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC/B,mEAAmE;IACnE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB,KAAK,CAAC,EAAE,MAAM,CAAA;CACf,CAAA;AAwFD,wFAAwF;AACxF,wBAAsB,wBAAwB,CAAC,IAAI,EAAE;IACnD,OAAO,EAAE,OAAO,CAAA;IAChB,GAAG,CAAC,EAAE,cAAc,CAAA;IACpB,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CACxB,GAAG,OAAO,CAAC,IAAI,CAAC,0BAA0B,EAAE,cAAc,CAAC,CAAC,CAoC5D;AA2LD;;;GAGG;AACH,wBAAsB,oBAAoB,CACxC,IAAI,EAAE,wBAAwB,GAC7B,OAAO,CAAC,0BAA0B,CAAC,CA8CrC"}
+{"version":3,"file":"reconcile.d.ts","sourceRoot":"","sources":["../../../src/services/achievement/reconcile.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,cAAc,EAAS,MAAM,SAAS,CAAA;AAc7D,MAAM,MAAM,0BAA0B,GAAG;IACvC,YAAY,EAAE,MAAM,CAAA;IACpB,qBAAqB,EAAE,MAAM,CAAA;IAC7B,iBAAiB,EAAE,MAAM,CAAA;IACzB,0BAA0B,EAAE,MAAM,CAAA;IAClC,mBAAmB,EAAE,MAAM,CAAA;IAC3B,eAAe,EAAE,MAAM,CAAA;IACvB,qBAAqB,EAAE,MAAM,CAAA;CAC9B,CAAA;AAED,MAAM,MAAM,wBAAwB,GAAG;IACrC,OAAO,EAAE,OAAO,CAAA;IAChB,GAAG,CAAC,EAAE,cAAc,CAAA;IACpB,2BAA2B;IAC3B,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACvB,8EAA8E;IAC9E,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC7B,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC/B,mEAAmE;IACnE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB,KAAK,CAAC,EAAE,MAAM,CAAA;CACf,CAAA;AAwFD,wFAAwF;AACxF,wBAAsB,wBAAwB,CAAC,IAAI,EAAE;IACnD,OAAO,EAAE,OAAO,CAAA;IAChB,GAAG,CAAC,EAAE,cAAc,CAAA;IACpB,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CACxB,GAAG,OAAO,CAAC,IAAI,CAAC,0BAA0B,EAAE,cAAc,CAAC,CAAC,CA2C5D;AA2LD;;;GAGG;AACH,wBAAsB,oBAAoB,CACxC,IAAI,EAAE,wBAAwB,GAC7B,OAAO,CAAC,0BAA0B,CAAC,CAgDrC"}

package/dist/services/achievement/reconcile.js

@@ -2,6 +2,7 @@ import { collectionOf } from '../../collections/helpers.js';
 import { syncCompositeProgression, } from './grantSideEffects.js';
 import { transitionLogData, transitionToId } from './logData.js';
 import { recordLog, syncTierChangedLog } from './recordEvent.js';
+import { rebuildMetricBalancesForUser } from './metricBalances.js';
 import { relationId } from './relationId.js';
 import { resolveCatalogId } from './resolveCatalog.js';
 import { syncTierProgression } from './tierProgression.js';
@@ -88,6 +89,12 @@ export async function reconcileUserProgression(args) {
     if (!req.context)
         req.context = {};
     const grantedLogsBackfilled = await backfillGrantedLogs({ req, userId: args.userId, scopeId });
+    const metricBalancesRebuilt = await rebuildMetricBalancesForUser({
+        payload: args.payload,
+        req,
+        userId: args.userId,
+        scopeId,
+    });
     const composites = await syncCompositeProgression({
         req,
         userId: args.userId,
@@ -106,6 +113,7 @@ export async function reconcileUserProgression(args) {
     });
     return {
         grantedLogsBackfilled,
+        metricBalancesRebuilt,
         compositesGranted: composites.granted,
         achievementRequestsEnsured: composites.requested,
         tierRequestsEnsured: tiers.requested,
@@ -276,6 +284,7 @@ export async function reconcileProgression(args) {
         achievementRequestsEnsured: 0,
         tierRequestsEnsured: 0,
         tierLogsWritten: 0,
+        metricBalancesRebuilt: 0,
     };
     for (const pair of pairs) {
         const result = await reconcileUserProgression({
@@ -290,6 +299,7 @@ export async function reconcileProgression(args) {
         totals.achievementRequestsEnsured += result.achievementRequestsEnsured;
         totals.tierRequestsEnsured += result.tierRequestsEnsured;
         totals.tierLogsWritten += result.tierLogsWritten;
+        totals.metricBalancesRebuilt += result.metricBalancesRebuilt;
     }
     return totals;
 }

package/dist/services/achievement/recordEvent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"recordEvent.d.ts","sourceRoot":"","sources":["../../../src/services/achievement/recordEvent.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,SAAS,CAAA;AAWtD,MAAM,MAAM,cAAc,GAAG;IAC3B,OAAO,EAAE,OAAO,CAAA;IAChB,GAAG,CAAC,EAAE,cAAc,CAAA;IACpB,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACvB,wDAAwD;IACxD,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACvB,sDAAsD;IACtD,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,8DAA8D;IAC9D,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAA;CACtC,CAAA;AAgBD,6DAA6D;AAC7D,wBAAsB,SAAS,CAAC,IAAI,EAAE,cAAc,wEAuCnD;AAED,4CAA4C;AAC5C,eAAO,MAAM,WAAW,kBAAY,CAAA;AAEpC;;GAEG;AACH,wBAAsB,kBAAkB,CAAC,IAAI,EAAE;IAC7C,OAAO,EAAE,OAAO,CAAA;IAChB,GAAG,CAAC,EAAE,cAAc,CAAA;IACpB,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACvB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CACxB,wEAiCA;AAED,6FAA6F;AAC7F,wBAAsB,kBAAkB,CAAC,IAAI,EAAE;IAC7C,OAAO,EAAE,OAAO,CAAA;IAChB,GAAG,CAAC,EAAE,cAAc,CAAA;IACpB,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CACxB,iFA0DA"}
+{"version":3,"file":"recordEvent.d.ts","sourceRoot":"","sources":["../../../src/services/achievement/recordEvent.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,SAAS,CAAA;AAatD,MAAM,MAAM,cAAc,GAAG;IAC3B,OAAO,EAAE,OAAO,CAAA;IAChB,GAAG,CAAC,EAAE,cAAc,CAAA;IACpB,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACvB,wDAAwD;IACxD,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACvB,sDAAsD;IACtD,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,8DAA8D;IAC9D,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAA;CACtC,CAAA;AAgBD,6DAA6D;AAC7D,wBAAsB,SAAS,CAAC,IAAI,EAAE,cAAc,wEAuCnD;AAED,4CAA4C;AAC5C,eAAO,MAAM,WAAW,kBAAY,CAAA;AAEpC;;GAEG;AACH,wBAAsB,kBAAkB,CAAC,IAAI,EAAE;IAC7C,OAAO,EAAE,OAAO,CAAA;IAChB,GAAG,CAAC,EAAE,cAAc,CAAA;IACpB,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACvB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CACxB,wEAsDA;AAED,6FAA6F;AAC7F,wBAAsB,kBAAkB,CAAC,IAAI,EAAE;IAC7C,OAAO,EAAE,OAAO,CAAA;IAChB,GAAG,CAAC,EAAE,cAAc,CAAA;IACpB,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CACxB,iFA0DA"}

package/dist/services/achievement/recordEvent.js

@@ -2,7 +2,9 @@ import { APIError } from 'payload';
 import { DEFAULT_ACHIEVEMENT_METRIC_SLUG } from '../../catalog.js';
 import { collectionOf } from '../../collections/helpers.js';
 import { eventTypeRequiresActor } from './eventTypeRequiresActor.js';
+import { applyMetricBalanceDelta } from './metricBalances.js';
 import { transitionLogData, transitionToId } from './logData.js';
+import { loadMetricDoc } from './resolveMetricValue.js';
 import { resolveCatalogId } from './resolveCatalog.js';
 import { resolveCurrentTier } from './resolveCurrentTier.js';
 import { userScopeWhere } from './where.js';
@@ -60,6 +62,17 @@ export const recordEvent = recordLog;
 export async function recordMetricChange(args) {
     const metricSlug = args.metric ?? DEFAULT_ACHIEVEMENT_METRIC_SLUG;
     const scopeId = args.scopeId ?? null;
+    const metricDoc = await loadMetricDoc({
+        payload: args.payload,
+        req: args.req,
+        metric: metricSlug,
+    });
+    if (!metricDoc) {
+        throw new APIError(`Unknown metric "${metricSlug}".`, 400);
+    }
+    if ((metricDoc.kind ?? 'stored') === 'computed') {
+        throw new APIError('Computed metrics cannot be changed with recordMetricChange.', 400);
+    }
     const log = await recordLog({
         payload: args.payload,
         req: args.req,
@@ -67,10 +80,18 @@ export async function recordMetricChange(args) {
         scopeId,
         type: 'metric.delta',
         actorId: args.actorId,
-        metric: metricSlug,
+        metric: metricDoc.id,
         change: args.change,
         reason: args.reason,
     });
+    await applyMetricBalanceDelta({
+        payload: args.payload,
+        req: args.req,
+        userId: args.userId,
+        scopeId,
+        metricId: metricDoc.id,
+        change: args.change,
+    });
     if (args.req) {
         const { syncTierProgression } = await import('./tierProgression.js');
         await syncTierProgression({

package/dist/services/achievement/resolveElapsedAnchor.d.ts

@@ -0,0 +1,15 @@
+import type { Payload, PayloadRequest } from 'payload';
+/**
+ * Resolve the start timestamp for elapsed rules / computed metrics.
+ * Built-ins: `user-created-at`, `first-event`. Host keys: `extensions.metricAnchors`.
+ */
+export declare function resolveElapsedAnchor(args: {
+    payload: Payload;
+    req?: PayloadRequest;
+    since?: unknown;
+    eventType?: unknown;
+    eventTypeSlug?: unknown;
+    userId: string;
+    scopeId: string | null;
+}): Promise<Date | null>;
+//# sourceMappingURL=resolveElapsedAnchor.d.ts.map

package/dist/services/achievement/resolveElapsedAnchor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolveElapsedAnchor.d.ts","sourceRoot":"","sources":["../../../src/services/achievement/resolveElapsedAnchor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,SAAS,CAAA;AA8CtD;;;GAGG;AACH,wBAAsB,oBAAoB,CAAC,IAAI,EAAE;IAC/C,OAAO,EAAE,OAAO,CAAA;IAChB,GAAG,CAAC,EAAE,cAAc,CAAA;IACpB,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,aAAa,CAAC,EAAE,OAAO,CAAA;IACvB,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;CACvB,GAAG,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC,CA0DvB"}

package/dist/services/achievement/resolveElapsedAnchor.js

@@ -0,0 +1,98 @@
+import { collectionOf } from '../../collections/helpers.js';
+import { getAchievementOptions } from '../../options-store.js';
+import { parseDate } from './duration.js';
+import { relationId } from './relationId.js';
+import { userScopeIncludingUnscopedWhere } from './where.js';
+async function resolveEventTypeId(args) {
+    let eventTypeId = relationId(args.eventType);
+    if (eventTypeId) {
+        const byId = await args.payload.find({
+            collection: collectionOf('eventTypes'),
+            depth: 0,
+            limit: 1,
+            overrideAccess: true,
+            req: args.req,
+            where: { id: { equals: eventTypeId } },
+        });
+        if (byId.docs[0])
+            return eventTypeId;
+    }
+    const slug = typeof args.eventTypeSlug === 'string'
+        ? args.eventTypeSlug
+        : typeof args.eventType === 'string'
+            ? args.eventType
+            : '';
+    if (!slug)
+        return null;
+    const found = await args.payload.find({
+        collection: collectionOf('eventTypes'),
+        depth: 0,
+        limit: 1,
+        overrideAccess: true,
+        req: args.req,
+        where: { slug: { equals: slug } },
+    });
+    return relationId(found.docs[0]);
+}
+/**
+ * Resolve the start timestamp for elapsed rules / computed metrics.
+ * Built-ins: `user-created-at`, `first-event`. Host keys: `extensions.metricAnchors`.
+ */
+export async function resolveElapsedAnchor(args) {
+    const since = String(args.since ?? 'user-created-at');
+    if (since === 'user-created-at') {
+        const usersSlug = getAchievementOptions().usersCollectionSlug ?? 'users';
+        try {
+            const user = (await args.payload.findByID({
+                collection: usersSlug,
+                id: args.userId,
+                depth: 0,
+                overrideAccess: true,
+                req: args.req,
+            }));
+            return parseDate(user?.createdAt);
+        }
+        catch {
+            return null;
+        }
+    }
+    if (since === 'first-event') {
+        const eventTypeId = await resolveEventTypeId({
+            payload: args.payload,
+            req: args.req,
+            eventType: args.eventType,
+            eventTypeSlug: args.eventTypeSlug,
+        });
+        if (!eventTypeId)
+            return null;
+        const logs = await args.payload.find({
+            collection: collectionOf('logs'),
+            depth: 0,
+            limit: 1,
+            overrideAccess: true,
+            req: args.req,
+            sort: 'createdAt',
+            where: {
+                and: [
+                    userScopeIncludingUnscopedWhere(args.userId, args.scopeId),
+                    { type: { equals: eventTypeId } },
+                ],
+            },
+        });
+        return parseDate(logs.docs[0]?.createdAt);
+    }
+    const hostAnchor = getAchievementOptions().extensions?.metricAnchors?.[since];
+    if (!hostAnchor)
+        return null;
+    try {
+        return parseDate(await hostAnchor({
+            payload: args.payload,
+            req: args.req,
+            userId: args.userId,
+            scopeId: args.scopeId,
+        }));
+    }
+    catch {
+        return null;
+    }
+}

package/dist/services/achievement/resolveMetricValue.d.ts

@@ -0,0 +1,32 @@
+import type { Payload, PayloadRequest } from 'payload';
+export type MetricDoc = {
+    id?: unknown;
+    slug?: string;
+    kind?: string | null;
+    compute?: string | null;
+    unit?: string | null;
+    since?: string | null;
+    eventType?: unknown;
+};
+export declare function loadMetricDoc(args: {
+    payload: Payload;
+    req?: PayloadRequest;
+    metric: string;
+}): Promise<(MetricDoc & {
+    id: string;
+}) | null>;
+/**
+ * Current numeric value for a metric (stored balance or computed elapsed).
+ */
+export declare function resolveMetricValue(args: {
+    payload: Payload;
+    req?: PayloadRequest;
+    /** Metric document id or slug, or a loaded metric doc. */
+    metric: string | (MetricDoc & {
+        id: string;
+    });
+    userId: string;
+    scopeId: string | null;
+    now?: Date;
+}): Promise<number>;
+//# sourceMappingURL=resolveMetricValue.d.ts.map

package/dist/services/achievement/resolveMetricValue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolveMetricValue.d.ts","sourceRoot":"","sources":["../../../src/services/achievement/resolveMetricValue.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,SAAS,CAAA;AAQtD,MAAM,MAAM,SAAS,GAAG;IACtB,EAAE,CAAC,EAAE,OAAO,CAAA;IACZ,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACpB,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACvB,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACpB,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACrB,SAAS,CAAC,EAAE,OAAO,CAAA;CACpB,CAAA;AAED,wBAAsB,aAAa,CAAC,IAAI,EAAE;IACxC,OAAO,EAAE,OAAO,CAAA;IAChB,GAAG,CAAC,EAAE,cAAc,CAAA;IACpB,MAAM,EAAE,MAAM,CAAA;CACf,GAAG,OAAO,CAAC,CAAC,SAAS,GAAG;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,CAAC,GAAG,IAAI,CAAC,CA+B/C;AAED;;GAEG;AACH,wBAAsB,kBAAkB,CAAC,IAAI,EAAE;IAC7C,OAAO,EAAE,OAAO,CAAA;IAChB,GAAG,CAAC,EAAE,cAAc,CAAA;IACpB,0DAA0D;IAC1D,MAAM,EAAE,MAAM,GAAG,CAAC,SAAS,GAAG;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;IAC7C,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB,GAAG,CAAC,EAAE,IAAI,CAAA;CACX,GAAG,OAAO,CAAC,MAAM,CAAC,CA8BlB"}

package/dist/services/achievement/resolveMetricValue.js

@@ -0,0 +1,73 @@
+import { collectionOf } from '../../collections/helpers.js';
+import { elapsedUnits } from './duration.js';
+import { findMetricBalance } from './metricBalances.js';
+import { relationId } from './relationId.js';
+import { resolveElapsedAnchor } from './resolveElapsedAnchor.js';
+export async function loadMetricDoc(args) {
+    const byId = relationId(args.metric);
+    if (byId && args.metric === byId) {
+        try {
+            const doc = (await args.payload.findByID({
+                collection: collectionOf('metrics'),
+                id: byId,
+                depth: 0,
+                overrideAccess: true,
+                req: args.req,
+            }));
+            if (doc)
+                return { ...doc, id: byId };
+        }
+        catch {
+            // fall through to slug lookup
+        }
+    }
+    const found = await args.payload.find({
+        collection: collectionOf('metrics'),
+        depth: 0,
+        limit: 1,
+        overrideAccess: true,
+        req: args.req,
+        where: {
+            or: [{ id: { equals: args.metric } }, { slug: { equals: args.metric } }],
+        },
+    });
+    const doc = found.docs[0];
+    const id = relationId(doc);
+    if (!doc || !id)
+        return null;
+    return { ...doc, id };
+}
+/**
+ * Current numeric value for a metric (stored balance or computed elapsed).
+ */
+export async function resolveMetricValue(args) {
+    const doc = typeof args.metric === 'string'
+        ? await loadMetricDoc({ payload: args.payload, req: args.req, metric: args.metric })
+        : args.metric;
+    if (!doc)
+        return 0;
+    const kind = doc.kind ?? 'stored';
+    if (kind === 'computed') {
+        if ((doc.compute ?? 'elapsed') !== 'elapsed')
+            return 0;
+        const anchor = await resolveElapsedAnchor({
+            payload: args.payload,
+            req: args.req,
+            since: doc.since,
+            eventType: doc.eventType,
+            userId: args.userId,
+            scopeId: args.scopeId,
+        });
+        if (!anchor)
+            return 0;
+        return elapsedUnits(anchor, doc.unit ?? 'days', args.now ?? new Date()) ?? 0;
+    }
+    const balance = await findMetricBalance({
+        payload: args.payload,
+        req: args.req,
+        userId: args.userId,
+        scopeId: args.scopeId,
+        metricId: doc.id,
+    });
+    return balance?.value ?? 0;
+}

package/dist/services/achievement/validateRules.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validateRules.d.ts","sourceRoot":"","sources":["../../../src/services/achievement/validateRules.ts"],"names":[],"mappings":"AAGA,OAAO,EAAsB,KAAK,SAAS,EAAE,MAAM,oBAAoB,CAAA;AAEvE;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,GAAG,IAAI,CAuD7E;AAED,sFAAsF;AACtF,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,IAAI,GAAG,SAAS,GAC9D,MAAM,GAAG,IAAI,CAOf;AAED,+EAA+E;AAC/E,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,IAAI,GAAG,SAAS,EAC/D,KAAK,EAAE,MAAM,GACZ,IAAI,CAKN"}
+{"version":3,"file":"validateRules.d.ts","sourceRoot":"","sources":["../../../src/services/achievement/validateRules.ts"],"names":[],"mappings":"AAGA,OAAO,EAAsB,KAAK,SAAS,EAAE,MAAM,oBAAoB,CAAA;AAEvE;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,GAAG,IAAI,CA0E7E;AAED,sFAAsF;AACtF,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,IAAI,GAAG,SAAS,GAC9D,MAAM,GAAG,IAAI,CAOf;AAED,+EAA+E;AAC/E,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,IAAI,GAAG,SAAS,EAC/D,KAAK,EAAE,MAAM,GACZ,IAAI,CAKN"}

package/dist/services/achievement/validateRules.js

@@ -49,6 +49,25 @@ export function validateRuleNode(rule) {
         }
         return null;
     }
+    if (type === 'elapsed-since') {
+        const since = String(rule.since ?? 'user-created-at');
+        if (since === 'first-event') {
+            if (!relationId(rule.eventType) && typeof rule.eventTypeSlug !== 'string') {
+                return 'Elapsed since (first event) needs an event type.';
+            }
+        }
+        else if (since !== 'user-created-at') {
+            return 'Elapsed since needs a valid since source.';
+        }
+        if (typeof rule.amount !== 'number' || Number.isNaN(rule.amount) || rule.amount < 0) {
+            return 'Elapsed since needs a non-negative amount.';
+        }
+        const unit = rule.unit ?? 'days';
+        if (unit !== 'days' && unit !== 'hours' && unit !== 'minutes') {
+            return 'Elapsed since unit must be days, hours, or minutes.';
+        }
+        return null;
+    }
     if (!type) {
         return 'Each rule needs a type.';
     }