@dappermountain/payload-plugin-achievements 0.1.0 → 0.2.0

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

@@ -0,0 +1,24 @@
+import type { Payload, PayloadRequest } from 'payload';
+export type ReconcileProgressionResult = {
+    usersScanned: number;
+    grantedLogsBackfilled: number;
+    compositesGranted: number;
+    achievementRequestsEnsured: number;
+    tierRequestsEnsured: number;
+    tierLogsWritten: number;
+};
+/** Repair progression for one user (+ optional scope) from current grants + catalog. */
+export declare function reconcileUserProgression(args: {
+    payload: Payload;
+    req?: PayloadRequest;
+    userId: string;
+    scopeId?: string | null;
+}): Promise<Omit<ReconcileProgressionResult, 'usersScanned'>>;
+/** Scan grants and reconcile each distinct (user, scope) pair. */
+export declare function reconcileProgression(args: {
+    payload: Payload;
+    req?: PayloadRequest;
+    scopeId?: string | null;
+    limit?: number;
+}): Promise<ReconcileProgressionResult>;
+//# sourceMappingURL=reconcile.d.ts.map

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

@@ -0,0 +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;AAY7D,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;AAoFD,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;AAOD,kEAAkE;AAClE,wBAAsB,oBAAoB,CAAC,IAAI,EAAE;IAC/C,OAAO,EAAE,OAAO,CAAA;IAChB,GAAG,CAAC,EAAE,cAAc,CAAA;IACpB,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACvB,KAAK,CAAC,EAAE,MAAM,CAAA;CACf,GAAG,OAAO,CAAC,0BAA0B,CAAC,CAyDtC"}

package/dist/services/achievement/reconcile.js

@@ -0,0 +1,170 @@
+import { collectionOf } from '../../collections/helpers';
+import { syncCompositeProgression, } from './grantSideEffects';
+import { recordLog, syncTierChangedLog } from './recordEvent';
+import { relationId } from './relationId';
+import { resolveCatalogId } from './resolveCatalog';
+import { syncTierProgression } from './tierProgression';
+import { userScopeWhere } from './where';
+async function backfillGrantedLogs(args) {
+    const typeId = await resolveCatalogId({
+        payload: args.req.payload,
+        req: args.req,
+        key: 'eventTypes',
+        slugOrId: 'achievement.granted',
+    });
+    const grants = await args.req.payload.find({
+        collection: collectionOf('grants'),
+        depth: 0,
+        limit: 500,
+        pagination: false,
+        overrideAccess: true,
+        req: args.req,
+        where: userScopeWhere(args.userId, args.scopeId),
+    });
+    const logs = await args.req.payload.find({
+        collection: collectionOf('logs'),
+        depth: 0,
+        limit: 500,
+        pagination: false,
+        overrideAccess: true,
+        req: args.req,
+        where: {
+            and: [userScopeWhere(args.userId, args.scopeId), { type: { equals: typeId } }],
+        },
+    });
+    const logged = new Set(logs.docs
+        .map((log) => relationId(log.data?.achievement))
+        .filter((id) => Boolean(id)));
+    let written = 0;
+    for (const grant of grants.docs) {
+        const achievementId = relationId(grant.achievement);
+        if (!achievementId || logged.has(achievementId))
+            continue;
+        let slug;
+        try {
+            const def = (await args.req.payload.findByID({
+                collection: collectionOf('achievements'),
+                id: achievementId,
+                depth: 0,
+                overrideAccess: true,
+                req: args.req,
+                select: { slug: true },
+            }));
+            slug = def?.slug;
+        }
+        catch {
+            // ignore
+        }
+        const completedAt = grant.completedAt;
+        await recordLog({
+            payload: args.req.payload,
+            req: args.req,
+            userId: args.userId,
+            scopeId: args.scopeId,
+            type: 'achievement.granted',
+            data: {
+                achievement: achievementId,
+                ...(slug ? { achievementSlug: slug } : {}),
+                backfilled: true,
+                ...(completedAt ? { completedAt } : {}),
+            },
+        });
+        logged.add(achievementId);
+        written += 1;
+    }
+    return written;
+}
+/** Repair progression for one user (+ optional scope) from current grants + catalog. */
+export async function reconcileUserProgression(args) {
+    const scopeId = args.scopeId ?? null;
+    const req = args.req ??
+        {
+            payload: args.payload,
+            context: {},
+        };
+    if (!req.context)
+        req.context = {};
+    const grantedLogsBackfilled = await backfillGrantedLogs({ req, userId: args.userId, scopeId });
+    const composites = await syncCompositeProgression({
+        req,
+        userId: args.userId,
+        scopeId,
+    });
+    const tiers = await syncTierProgression({
+        req,
+        userId: args.userId,
+        scopeId,
+    });
+    const tierLog = await syncTierChangedLog({
+        payload: args.payload,
+        req,
+        userId: args.userId,
+        scopeId,
+    });
+    return {
+        grantedLogsBackfilled,
+        compositesGranted: composites.granted,
+        achievementRequestsEnsured: composites.requested,
+        tierRequestsEnsured: tiers.requested,
+        tierLogsWritten: tierLog ? 1 : 0,
+    };
+}
+function scopeKey(scope) {
+    const id = relationId(scope);
+    return id ?? '';
+}
+/** Scan grants and reconcile each distinct (user, scope) pair. */
+export async function reconcileProgression(args) {
+    const req = args.req ??
+        {
+            payload: args.payload,
+            context: {},
+        };
+    if (!req.context)
+        req.context = {};
+    const where = args.scopeId
+        ? { scope: { equals: args.scopeId } }
+        : undefined;
+    const grants = await args.payload.find({
+        collection: collectionOf('grants'),
+        depth: 0,
+        limit: args.limit ?? 5000,
+        pagination: false,
+        overrideAccess: true,
+        req,
+        ...(where ? { where } : {}),
+    });
+    const pairs = new Map();
+    for (const grant of grants.docs) {
+        const userId = relationId(grant.user);
+        if (!userId)
+            continue;
+        const scopeId = relationId(grant.scope);
+        const key = `${userId}::${scopeKey(scopeId)}`;
+        if (!pairs.has(key))
+            pairs.set(key, { userId, scopeId });
+    }
+    const totals = {
+        usersScanned: 0,
+        grantedLogsBackfilled: 0,
+        compositesGranted: 0,
+        achievementRequestsEnsured: 0,
+        tierRequestsEnsured: 0,
+        tierLogsWritten: 0,
+    };
+    for (const pair of pairs.values()) {
+        const result = await reconcileUserProgression({
+            payload: args.payload,
+            req,
+            userId: pair.userId,
+            scopeId: pair.scopeId,
+        });
+        totals.usersScanned += 1;
+        totals.grantedLogsBackfilled += result.grantedLogsBackfilled;
+        totals.compositesGranted += result.compositesGranted;
+        totals.achievementRequestsEnsured += result.achievementRequestsEnsured;
+        totals.tierRequestsEnsured += result.tierRequestsEnsured;
+        totals.tierLogsWritten += result.tierLogsWritten;
+    }
+    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,wEAwBA;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,iFAgDA"}
+{"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,iFAgDA"}

package/dist/services/achievement/recordEvent.js

@@ -71,6 +71,14 @@ export async function recordMetricChange(args) {
         change: args.change,
         reason: args.reason,
     });
+    if (args.req) {
+        const { syncTierProgression } = await import('./tierProgression');
+        await syncTierProgression({
+            req: args.req,
+            userId: args.userId,
+            scopeId,
+        });
+    }
     await syncTierChangedLog({
         payload: args.payload,
         req: args.req,

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

@@ -8,7 +8,7 @@ export type ResolvedTier = {
 };
 /**
  * Derive current tier by walking unlock rules in rank order (lowest first).
- * Empty unlock rules pass. `tier-at-least` uses the rank unlocked so far on this walk.
+ * Empty unlock rules pass. Tiers with `requiresReview` only count once an approved tier request exists.
  */
 export declare function resolveCurrentTier(args: {
     payload: Payload;

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

@@ -1 +1 @@
-{"version":3,"file":"resolveCurrentTier.d.ts","sourceRoot":"","sources":["../../../src/services/achievement/resolveCurrentTier.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,SAAS,CAAA;AAMtD,MAAM,MAAM,YAAY,GAAG;IACzB,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;CACvB,CAAA;AAWD;;;GAGG;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,4EAA4E;IAC5E,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAoD/B"}
+{"version":3,"file":"resolveCurrentTier.d.ts","sourceRoot":"","sources":["../../../src/services/achievement/resolveCurrentTier.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,SAAS,CAAA;AAOtD,MAAM,MAAM,YAAY,GAAG;IACzB,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;CACvB,CAAA;AAYD;;;GAGG;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,4EAA4E;IAC5E,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CA6D/B"}

package/dist/services/achievement/resolveCurrentTier.js

@@ -1,9 +1,10 @@
 import { collectionOf } from '../../collections/helpers';
 import { evaluateRules } from './evaluateRules';
 import { relationId } from './relationId';
+import { hasApprovedTierRequest } from './tierApproval';
 /**
  * Derive current tier by walking unlock rules in rank order (lowest first).
- * Empty unlock rules pass. `tier-at-least` uses the rank unlocked so far on this walk.
+ * Empty unlock rules pass. Tiers with `requiresReview` only count once an approved tier request exists.
  */
 export async function resolveCurrentTier(args) {
     if (!args.userId)
@@ -25,7 +26,6 @@ export async function resolveCurrentTier(args) {
         ...(where ? { where } : {}),
     });
     const tiers = [...result.docs].sort((a, b) => Number(a.rank ?? 0) - Number(b.rank ?? 0));
-    // evaluateRules requires a PayloadRequest; synthesize a minimal one when only payload is passed.
     const req = (args.req ?? { payload: args.payload });
     let current = null;
     for (const tier of tiers) {
@@ -39,6 +39,16 @@ export async function resolveCurrentTier(args) {
         });
         if (!unlocked)
             continue;
+        if (tier.requiresReview === true) {
+            const approved = await hasApprovedTierRequest({
+                req,
+                userId: args.userId,
+                tierId: String(tier.id),
+                scopeId,
+            });
+            if (!approved)
+                break;
+        }
         current = {
             id: String(tier.id),
             rank: Number(tier.rank ?? 0),

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

@@ -10,12 +10,14 @@ export declare function submitAchievementRequest(args: {
     scopeId?: string | null;
     note?: string;
 }): Promise<import("payload").JsonObject & import("payload").TypeWithID>;
-/** Create a grant row, emit achievement.granted, sync tier.changed when the ladder moves. */
+/**
+ * Create a grant row. Side effects (logs, composites, tiers) run in Grants hooks.
+ */
 export declare function grantAchievement(args: {
     req: PayloadRequest;
     userId: string;
     achievementId: string;
     scopeId?: string | null;
     note?: string | null;
-}): Promise<import("payload").JsonObject & import("payload").TypeWithID>;
+}): Promise<Record<string, unknown>>;
 //# sourceMappingURL=submitAchievementRequest.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"submitAchievementRequest.d.ts","sourceRoot":"","sources":["../../../src/services/achievement/submitAchievementRequest.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAS,MAAM,SAAS,CAAA;AAMpD;;;GAGG;AACH,wBAAsB,wBAAwB,CAAC,IAAI,EAAE;IACnD,GAAG,EAAE,cAAc,CAAA;IACnB,MAAM,EAAE,MAAM,CAAA;IACd,aAAa,EAAE,MAAM,CAAA;IACrB,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACvB,IAAI,CAAC,EAAE,MAAM,CAAA;CACd,wEAeA;AAED,6FAA6F;AAC7F,wBAAsB,gBAAgB,CAAC,IAAI,EAAE;IAC3C,GAAG,EAAE,cAAc,CAAA;IACnB,MAAM,EAAE,MAAM,CAAA;IACd,aAAa,EAAE,MAAM,CAAA;IACrB,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACvB,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CACrB,wEAqEA"}
+{"version":3,"file":"submitAchievementRequest.d.ts","sourceRoot":"","sources":["../../../src/services/achievement/submitAchievementRequest.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAA;AAK7C;;;GAGG;AACH,wBAAsB,wBAAwB,CAAC,IAAI,EAAE;IACnD,GAAG,EAAE,cAAc,CAAA;IACnB,MAAM,EAAE,MAAM,CAAA;IACd,aAAa,EAAE,MAAM,CAAA;IACrB,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACvB,IAAI,CAAC,EAAE,MAAM,CAAA;CACd,wEAcA;AAED;;GAEG;AACH,wBAAsB,gBAAgB,CAAC,IAAI,EAAE;IAC3C,GAAG,EAAE,cAAc,CAAA;IACnB,MAAM,EAAE,MAAM,CAAA;IACd,aAAa,EAAE,MAAM,CAAA;IACrB,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACvB,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CACrB,oCAQA"}

package/dist/services/achievement/submitAchievementRequest.js

@@ -1,6 +1,5 @@
 import { collectionOf } from '../../collections/helpers';
-import { evaluateRules, ruleGroupHasProgressRequirements } from './evaluateRules';
-import { recordLog, syncTierChangedLog } from './recordEvent';
+import { createGrantRow } from './grantSideEffects';
 /**
  * Create an achievement request (or auto-approved grant) via the collection.
  * Hooks bind the requesting user, check eligibility, and grant when approved.
@@ -9,7 +8,6 @@ export async function submitAchievementRequest(args) {
     return args.req.payload.create({
         collection: collectionOf('achievementRequests'),
         data: {
-            // user is overwritten from req.user in beforeValidate
             user: args.userId,
             scope: args.scopeId ?? undefined,
             achievement: args.achievementId,
@@ -21,106 +19,15 @@ export async function submitAchievementRequest(args) {
         user: args.req.user ?? undefined,
     });
 }
-/** Create a grant row, emit achievement.granted, sync tier.changed when the ladder moves. */
+/**
+ * Create a grant row. Side effects (logs, composites, tiers) run in Grants hooks.
+ */
 export async function grantAchievement(args) {
-    const scopeId = args.scopeId ?? null;
-    const achievementId = args.achievementId;
-    const definition = (await args.req.payload.findByID({
-        collection: collectionOf('achievements'),
-        id: achievementId,
-        depth: 0,
-        overrideAccess: true,
-        req: args.req,
-    }));
-    const clauses = [
-        { user: { equals: args.userId } },
-        { achievement: { equals: achievementId } },
-    ];
-    if (scopeId)
-        clauses.push({ scope: { equals: scopeId } });
-    else
-        clauses.push({ scope: { exists: false } });
-    const existing = await args.req.payload.find({
-        collection: collectionOf('grants'),
-        depth: 0,
-        limit: 1,
-        overrideAccess: true,
-        req: args.req,
-        where: { and: clauses },
-    });
-    if (existing.docs[0])
-        return existing.docs[0];
-    const result = await args.req.payload.create({
-        collection: collectionOf('grants'),
-        data: {
-            user: args.userId,
-            scope: scopeId ?? undefined,
-            achievement: achievementId,
-            completedAt: new Date().toISOString(),
-            ...(args.note ? { note: args.note } : {}),
-        },
-        overrideAccess: true,
-        req: args.req,
-    });
-    await recordLog({
-        payload: args.req.payload,
+    return createGrantRow({
         req: args.req,
         userId: args.userId,
-        scopeId,
-        type: 'achievement.granted',
-        data: {
-            achievement: achievementId,
-            ...(definition?.slug ? { achievementSlug: definition.slug } : {}),
-        },
-    });
-    await syncCompositeGrants({
-        req: args.req,
-        userId: args.userId,
-        scopeId,
-    });
-    await syncTierChangedLog({
-        payload: args.req.payload,
-        req: args.req,
-        userId: args.userId,
-        scopeId,
-    });
-    return result;
-}
-async function syncCompositeGrants(args) {
-    const where = args.scopeId
-        ? { or: [{ scope: { equals: args.scopeId } }, { scope: { exists: false } }] }
-        : undefined;
-    const catalog = await args.req.payload.find({
-        collection: collectionOf('achievements'),
-        depth: 0,
-        limit: 200,
-        pagination: false,
-        overrideAccess: true,
-        req: args.req,
-        ...(where ? { where } : {}),
+        achievementId: args.achievementId,
+        scopeId: args.scopeId,
+        note: args.note,
     });
-    for (const doc of catalog.docs) {
-        const def = doc;
-        if (def.requiresReview !== false)
-            continue;
-        if (!ruleGroupHasProgressRequirements(def.completionRules))
-            continue;
-        if (String(def.id) === '')
-            continue;
-        const complete = await evaluateRules({
-            payload: args.req.payload,
-            req: args.req,
-            rules: def.completionRules,
-            userId: args.userId,
-            scopeId: args.scopeId,
-        });
-        if (!complete)
-            continue;
-        await grantAchievement({
-            req: args.req,
-            userId: args.userId,
-            achievementId: String(def.id),
-            scopeId: args.scopeId,
-        });
-    }
 }

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

@@ -0,0 +1,8 @@
+import type { PayloadRequest } from 'payload';
+export declare function hasApprovedTierRequest(args: {
+    req: PayloadRequest;
+    userId: string;
+    tierId: string;
+    scopeId: string | null;
+}): Promise<boolean>;
+//# sourceMappingURL=tierApproval.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tierApproval.d.ts","sourceRoot":"","sources":["../../../src/services/achievement/tierApproval.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAS,MAAM,SAAS,CAAA;AAIpD,wBAAsB,sBAAsB,CAAC,IAAI,EAAE;IACjD,GAAG,EAAE,cAAc,CAAA;IACnB,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;CACvB,GAAG,OAAO,CAAC,OAAO,CAAC,CAkBnB"}

package/dist/services/achievement/tierApproval.js

@@ -0,0 +1,21 @@
+import { collectionOf } from '../../collections/helpers';
+export async function hasApprovedTierRequest(args) {
+    const clauses = [
+        { user: { equals: args.userId } },
+        { tier: { equals: args.tierId } },
+        { status: { equals: 'approved' } },
+    ];
+    if (args.scopeId)
+        clauses.push({ scope: { equals: args.scopeId } });
+    else
+        clauses.push({ scope: { exists: false } });
+    const existing = await args.req.payload.find({
+        collection: collectionOf('tierRequests'),
+        depth: 0,
+        limit: 1,
+        overrideAccess: true,
+        req: args.req,
+        where: { and: clauses },
+    });
+    return Boolean(existing.docs[0]);
+}

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

@@ -0,0 +1,22 @@
+import type { PayloadRequest } from 'payload';
+export declare function ensureTierRequest(args: {
+    req: PayloadRequest;
+    userId: string;
+    tierId: string;
+    scopeId: string | null;
+}): Promise<{
+    doc: Record<string, unknown>;
+    created: boolean;
+}>;
+/**
+ * When unlock rules pass and the tier requires review, ensure a pending/approved request exists.
+ */
+export declare function syncTierProgression(args: {
+    req: PayloadRequest;
+    userId: string;
+    scopeId: string | null;
+}): Promise<{
+    requested: number;
+}>;
+export { hasApprovedTierRequest } from './tierApproval';
+//# sourceMappingURL=tierProgression.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tierProgression.d.ts","sourceRoot":"","sources":["../../../src/services/achievement/tierProgression.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAS,MAAM,SAAS,CAAA;AAgBpD,wBAAsB,iBAAiB,CAAC,IAAI,EAAE;IAC5C,GAAG,EAAE,cAAc,CAAA;IACnB,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;CACvB,GAAG,OAAO,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CAAC,CAsC9D;AAED;;GAEG;AACH,wBAAsB,mBAAmB,CAAC,IAAI,EAAE;IAC9C,GAAG,EAAE,cAAc,CAAA;IACnB,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;CACvB,GAAG,OAAO,CAAC;IAAE,SAAS,EAAE,MAAM,CAAA;CAAE,CAAC,CA0DjC;AAED,OAAO,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAA"}

package/dist/services/achievement/tierProgression.js

@@ -0,0 +1,100 @@
+import { collectionOf } from '../../collections/helpers';
+import { CTX_SYSTEM_REQUEST } from './contextFlags';
+import { evaluateRules } from './evaluateRules';
+import { hasApprovedTierRequest } from './tierApproval';
+export async function ensureTierRequest(args) {
+    const clauses = [
+        { user: { equals: args.userId } },
+        { tier: { equals: args.tierId } },
+        { status: { in: ['pending', 'approved'] } },
+    ];
+    if (args.scopeId)
+        clauses.push({ scope: { equals: args.scopeId } });
+    else
+        clauses.push({ scope: { exists: false } });
+    const existing = await args.req.payload.find({
+        collection: collectionOf('tierRequests'),
+        depth: 0,
+        limit: 1,
+        overrideAccess: true,
+        req: args.req,
+        where: { and: clauses },
+    });
+    if (existing.docs[0]) {
+        return { doc: existing.docs[0], created: false };
+    }
+    args.req.context[CTX_SYSTEM_REQUEST] = true;
+    try {
+        const doc = (await args.req.payload.create({
+            collection: collectionOf('tierRequests'),
+            data: {
+                user: args.userId,
+                scope: args.scopeId ?? undefined,
+                tier: args.tierId,
+                status: 'pending',
+            },
+            overrideAccess: true,
+            req: args.req,
+        }));
+        return { doc, created: true };
+    }
+    finally {
+        delete args.req.context[CTX_SYSTEM_REQUEST];
+    }
+}
+/**
+ * When unlock rules pass and the tier requires review, ensure a pending/approved request exists.
+ */
+export async function syncTierProgression(args) {
+    const scopeId = args.scopeId;
+    const where = scopeId
+        ? { or: [{ scope: { equals: scopeId } }, { scope: { exists: false } }] }
+        : undefined;
+    const result = await args.req.payload.find({
+        collection: collectionOf('tiers'),
+        depth: 0,
+        limit: 100,
+        pagination: false,
+        overrideAccess: true,
+        req: args.req,
+        sort: 'rank',
+        ...(where ? { where } : {}),
+    });
+    const tiers = [...result.docs].sort((a, b) => Number(a.rank ?? 0) - Number(b.rank ?? 0));
+    let requested = 0;
+    let ladderRank = null;
+    for (const tier of tiers) {
+        const unlocked = await evaluateRules({
+            payload: args.req.payload,
+            req: args.req,
+            rules: tier.unlockRules,
+            userId: args.userId,
+            scopeId,
+            ladderRank,
+        });
+        if (!unlocked)
+            continue;
+        if (tier.requiresReview === true) {
+            const { created } = await ensureTierRequest({
+                req: args.req,
+                userId: args.userId,
+                tierId: String(tier.id),
+                scopeId,
+            });
+            const approved = await hasApprovedTierRequest({
+                req: args.req,
+                userId: args.userId,
+                tierId: String(tier.id),
+                scopeId,
+            });
+            if (!approved) {
+                if (created)
+                    requested += 1;
+                break;
+            }
+        }
+        ladderRank = Number(tier.rank ?? 0);
+    }
+    return { requested };
+}
+export { hasApprovedTierRequest } from './tierApproval';

package/dist/types.d.ts

@@ -33,7 +33,7 @@ export type AchievementRuleType = {
     progressRole?: 'requirement' | 'gate';
 };
 /** Logical collection ids — map to configurable slugs via `collections`. */
-export type AchievementCollectionKey = 'tiers' | 'achievements' | 'grants' | 'achievementRequests' | 'logs' | 'eventTypes' | 'metrics';
+export type AchievementCollectionKey = 'tiers' | 'achievements' | 'grants' | 'achievementRequests' | 'tierRequests' | 'logs' | 'eventTypes' | 'metrics';
 /**
  * Host overrides layered onto a plugin collection (Form Builder–style).
  * Access/admin merge shallowly; hook arrays are appended after plugin hooks.
@@ -80,6 +80,12 @@ export type AchievementEndpointsOptions = {
      * Pass `false` to skip registering the endpoint.
      */
     me?: string | false;
+    /**
+     * Root REST path to repair progression from existing grants (`POST`).
+     * Default: `'/achievements/reconcile'`. Requires host `canReview`.
+     * Pass `false` to skip.
+     */
+    reconcile?: string | false;
 };
 export type AchievementPluginOptions = {
     /**
@@ -113,5 +119,5 @@ export type AchievementPluginOptions = {
 };
 export type BuiltInRuleType = 'achievement-complete' | 'event-count' | 'metric-minimum' | 'tier-at-least';
 /** Engine log-type catalog slugs (seeded as system catalog rows). */
-export type BuiltInEventType = 'achievement.granted' | 'metric.delta' | 'tier.changed';
+export type BuiltInEventType = 'achievement.granted' | 'achievement.revoked' | 'metric.delta' | 'tier.changed';
 //# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dappermountain/payload-plugin-achievements",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "A robust, Admin-configured achievements engine for Payload: composable unlock rules, derived rank progress, request/review grants, metrics, and scoped multi-tenant support.",
   "license": "MIT",
   "type": "module",
@@ -69,15 +69,15 @@
     "react": "^19.0.0"
   },
   "devDependencies": {
+    "@dappermountain/agent-payload": "^0.1.5",
+    "@dappermountain/agent-practices": "^0.1.2",
     "@payloadcms/ui": "3.88.0",
+    "@types/bun": "1.4.0",
     "@types/react": "^19.0.0",
     "payload": "3.88.0",
-    "react": "19.2.4",
-    "typescript": "5.9.2",
     "prettier": "^3.6.2",
-    "@types/bun": "1.4.0",
-    "@dappermountain/agent-practices": "^0.1.0",
-    "@dappermountain/agent-payload": "^0.1.0"
+    "react": "19.2.4",
+    "typescript": "5.9.2"
   },
   "engines": {
     "node": ">=20"