@dappermountain/payload-plugin-achievements 0.3.0 → 0.3.1

package/README.md

@@ -124,7 +124,11 @@ Unlock (tiers), eligibility, and completion (achievements) share the same rule t
 
 **Stored metrics** — totals live in `achievement-metric-balances`, updated by `recordMetricChange` (log + balance dual-write). Logs remain the audit/rebuild source; reconcile backfills balances.
 
-**Leaderboards** — `getMetricLeaderboard` / `GET /api/achievements/leaderboard?metric=points` ranks stored balances (authenticated). Disable with `endpoints.leaderboard: false`.
+**Leaderboards** — `getMetricLeaderboard` / `GET /api/achievements/leaderboard?metric=points` ranks **stored** metric balances (authenticated, optional `scope`). Computed/elapsed metrics (e.g. tenure days) have no balance rows and are rejected — resolve a single user with `resolveMetricValue`, or materialize snapshots if you need a ranked computed board. Disable with `endpoints.leaderboard: false`. Hosts compose member directories (names, current tier, earned counts, who may appear) themselves; the plugin returns `{ user, value, rank }` only.
+
+**Unlock checklist** — `buildUnlockRequirementLeaves` walks a rule tree (including Payload leaves that carry empty `rules: []`), evaluates met/progress per leaf, and returns catalog subjects (`relations`, `target`, `unit`, `since`). It does **not** build UI copy — hosts format labels. `achievement-complete` is omitted by default so those stay on catalog groups. `eachRuleLeaf` is also exported if you need the walker alone.
+
+**Review snapshot** — `getUserProgress({ include: { reviews: true } })` or `loadUserProgressReviews` adds pending achievement keys and open/rejected tier requests so hosts do not re-query the engine for badge state.
 
 **System catalog** — by default the plugin runs `seedAchievementCatalog` on Payload `onInit` (opt out with `seedSystemCatalog: false`). Hosts still seed product catalog + locales via `seedAchievements`.
 
@@ -230,11 +234,11 @@ 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. |
+| `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. Optional `?reviews=1` adds `reviews`. |
+| `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 (`me`): `scope`, `limit`, `page`, `requestsLimit`. Leaderboard: `metric` (required), `scope`, `limit`, `page`.
+Query params (`me`): `scope`, `limit`, `page`, `requestsLimit`, `reviews`. Leaderboard: `metric` (required), `scope`, `limit`, `page`.
 
 ### `extensions.ruleTypes` / `metricAnchors`
 
@@ -285,14 +289,25 @@ import {
   resolveCurrentTier,
   resolveTierProgress,
   getUserProgress,
+  loadUserProgressReviews,
+  buildUnlockRequirementLeaves,
   submitAchievementRequest,
   reviewAchievementRequest,
 } from '@dappermountain/payload-plugin-achievements'
 
 await recordLog({ payload, userId, scopeId, type: 'host.custom-kind', actorId })
 await recordMetricChange({ payload, userId, scopeId, metric: 'points', change: 10 })
+const points = await resolveMetricValue({ payload, userId, scopeId, metric: 'points' })
 const board = await getMetricLeaderboard({ payload, metric: 'points', scopeId, limit: 20 })
 const tier = await resolveCurrentTier({ payload, userId, scopeId })
+const progress = await getUserProgress({ payload, userId, scopeId, include: { reviews: true } })
+const unlockLeaves = await buildUnlockRequirementLeaves({
+  payload,
+  userId,
+  scopeId,
+  rules: nextTier.unlockRules,
+  ladderRank: tier?.rank ?? null,
+})
 
 // Repair users whose grants predate side-effect hooks (idempotent)
 await reconcileProgression({ payload })
@@ -334,7 +349,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` |
+| Current user snapshot | `GET /api/achievements/me?scope=<scopeId>&limit=10&page=1` (`&reviews=1` for pending/rejected review keys) |
 | 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>` |

package/dist/endpoints/me.d.ts

@@ -1,7 +1,8 @@
 import type { Endpoint } from 'payload';
 /**
  * `GET` current user’s snapshot. Body is Payload `find`-shaped for **grants**,
- * plus ladder-derived `tiers` and lean `requests`. Optional `?scope=` / `limit` / `page`.
+ * plus ladder-derived `tiers` and lean `requests`. Optional `?scope=` / `limit` / `page`
+ * / `reviews=1` (pending achievement keys + open/rejected tier requests).
  */
 export declare function buildMeEndpoint(path: string): Endpoint;
 //# sourceMappingURL=me.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"me.d.ts","sourceRoot":"","sources":["../../src/endpoints/me.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAkB,MAAM,SAAS,CAAA;AA+BvD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,CAqBtD"}
+{"version":3,"file":"me.d.ts","sourceRoot":"","sources":["../../src/endpoints/me.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAkB,MAAM,SAAS,CAAA;AAoCvD;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,CAsBtD"}

package/dist/endpoints/me.js

@@ -24,9 +24,14 @@ function pagingFromRequest(req) {
         requestsLimit: positiveInt(params?.get('requestsLimit') ?? null, 20),
     };
 }
+function reviewsFromRequest(req) {
+    const raw = requestUrl(req)?.searchParams.get('reviews');
+    return raw === '1' || raw === 'true';
+}
 /**
  * `GET` current user’s snapshot. Body is Payload `find`-shaped for **grants**,
- * plus ladder-derived `tiers` and lean `requests`. Optional `?scope=` / `limit` / `page`.
+ * plus ladder-derived `tiers` and lean `requests`. Optional `?scope=` / `limit` / `page`
+ * / `reviews=1` (pending achievement keys + open/rejected tier requests).
  */
 export function buildMeEndpoint(path) {
     return {
@@ -43,6 +48,7 @@ export function buildMeEndpoint(path) {
                 userId,
                 scopeId: scopeFromRequest(req),
                 paging: pagingFromRequest(req),
+                include: reviewsFromRequest(req) ? { reviews: true } : undefined,
             });
             return Response.json(body);
         },

package/dist/index.d.ts

@@ -3,12 +3,13 @@ export type { EngineEventTypeSlug, EngineMetricSlug } from './catalog.js';
 export { achievementPlugin } from './plugin.js';
 export { seedAchievementCatalog, seedAchievements } from './seed/index.js';
 export type { AchievementSeedAchievement, AchievementSeedCatalogRow, AchievementSeedInput, AchievementSeedLocalizedText, AchievementSeedTier, } from './seed/index.js';
-export { evaluateRules, evaluateRuleProgress, collectAchievementCompleteRefs, buildCatalogProgressGroups, getUserProgress, getMetricLeaderboard, grantAchievement, loadMetricDoc, recordEvent, recordLog, recordMetricChange, rebuildMetricBalance, rebuildMetricBalancesForUser, reconcileProgression, reconcileUserProgression, releasePendingAchievementReviews, releasePendingTierReviews, resolveCurrentTier, resolveElapsedAnchor, resolveMetricValue, resolveTierProgress, reviewAchievementRequest, submitAchievementRequest, syncTierChangedLog, syncTierProgression, syncCompositeProgression, catalogRef, transitionLogData, transitionToId, validateRuleGroup, validateRuleNode, } from './services/achievement/index.js';
-export type { ResolvedTier, RuleGroup, TierLadderProgress, CatalogProgressGroup, CatalogProgressItem, CatalogRef, TransitionLogData, MetricLeaderboardResult, MetricLeaderboardRow, ReconcileProgressionArgs, ReconcileProgressionResult, ReleaseReviewGateResult, } from './services/achievement/index.js';
+export { evaluateRules, evaluateRuleProgress, collectAchievementCompleteRefs, buildCatalogProgressGroups, buildUnlockRequirementLeaves, getUserProgress, loadUserProgressReviews, getMetricLeaderboard, grantAchievement, loadMetricDoc, recordEvent, recordLog, recordMetricChange, rebuildMetricBalance, rebuildMetricBalancesForUser, reconcileProgression, reconcileUserProgression, releasePendingAchievementReviews, releasePendingTierReviews, resolveCurrentTier, resolveElapsedAnchor, resolveMetricValue, resolveTierProgress, reviewAchievementRequest, submitAchievementRequest, syncTierChangedLog, syncTierProgression, syncCompositeProgression, catalogRef, transitionLogData, transitionToId, validateRuleGroup, validateRuleNode, } from './services/achievement/index.js';
+export type { ResolvedTier, RuleGroup, TierLadderProgress, CatalogProgressGroup, CatalogProgressItem, UnlockRequirementLeaf, UnlockRequirementRelation, GetUserProgressInclude, UserProgressMeResponse, UserProgressReviews, UserProgressTierRequest, CatalogRef, TransitionLogData, MetricLeaderboardResult, MetricLeaderboardRow, ReconcileProgressionArgs, ReconcileProgressionResult, ReleaseReviewGateResult, } from './services/achievement/index.js';
 export type { BuiltInEventType, BuiltInRuleType, AchievementCollectionKey, AchievementCollectionOverride, AchievementCollectionsOptions, AchievementEndpointsOptions, AchievementMetricAnchor, AchievementMetricAnchorConfig, AchievementMetricAnchorEntry, AchievementPluginOptions, AchievementRuleType, AchievementScopeConfig, AchievementUsersOptions, } from './types.js';
 export { DEFAULT_COLLECTION_BASE_SLUGS, DEFAULT_COLLECTION_PREFIX, DEFAULT_ADMIN_GROUP } from './collections/slugs.js';
 export { DEFAULT_ME_ENDPOINT_PATH, DEFAULT_LEADERBOARD_ENDPOINT_PATH, DEFAULT_RECONCILE_ENDPOINT_PATH, } from './defaults.js';
 export { collectionOf, slugOf } from './collections/helpers.js';
+export { eachRuleLeaf } from './collections/hooks/eachRuleLeaf.js';
 export { isAchievementPluginEnabled } from './enabled.js';
 export { descriptionToPlaintext } from './fields/descriptionPlaintext.js';
 export { plainTextToLexical } from './fields/plainTextToLexical.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,0BAA0B,EAC1B,+BAA+B,EAC/B,kBAAkB,EAClB,cAAc,GACf,MAAM,cAAc,CAAA;AACrB,YAAY,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAA;AACzE,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAA;AAC/C,OAAO,EAAE,sBAAsB,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAA;AAC1E,YAAY,EACV,0BAA0B,EAC1B,yBAAyB,EACzB,oBAAoB,EACpB,4BAA4B,EAC5B,mBAAmB,GACpB,MAAM,iBAAiB,CAAA;AACxB,OAAO,EACL,aAAa,EACb,oBAAoB,EACpB,8BAA8B,EAC9B,0BAA0B,EAC1B,eAAe,EACf,oBAAoB,EACpB,gBAAgB,EAChB,aAAa,EACb,WAAW,EACX,SAAS,EACT,kBAAkB,EAClB,oBAAoB,EACpB,4BAA4B,EAC5B,oBAAoB,EACpB,wBAAwB,EACxB,gCAAgC,EAChC,yBAAyB,EACzB,kBAAkB,EAClB,oBAAoB,EACpB,kBAAkB,EAClB,mBAAmB,EACnB,wBAAwB,EACxB,wBAAwB,EACxB,kBAAkB,EAClB,mBAAmB,EACnB,wBAAwB,EACxB,UAAU,EACV,iBAAiB,EACjB,cAAc,EACd,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,iCAAiC,CAAA;AACxC,YAAY,EACV,YAAY,EACZ,SAAS,EACT,kBAAkB,EAClB,oBAAoB,EACpB,mBAAmB,EACnB,UAAU,EACV,iBAAiB,EACjB,uBAAuB,EACvB,oBAAoB,EACpB,wBAAwB,EACxB,0BAA0B,EAC1B,uBAAuB,GACxB,MAAM,iCAAiC,CAAA;AACxC,YAAY,EACV,gBAAgB,EAChB,eAAe,EACf,wBAAwB,EACxB,6BAA6B,EAC7B,6BAA6B,EAC7B,2BAA2B,EAC3B,uBAAuB,EACvB,6BAA6B,EAC7B,4BAA4B,EAC5B,wBAAwB,EACxB,mBAAmB,EACnB,sBAAsB,EACtB,uBAAuB,GACxB,MAAM,YAAY,CAAA;AACnB,OAAO,EAAE,6BAA6B,EAAE,yBAAyB,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAA;AACtH,OAAO,EACL,wBAAwB,EACxB,iCAAiC,EACjC,+BAA+B,GAChC,MAAM,eAAe,CAAA;AACtB,OAAO,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,0BAA0B,CAAA;AAC/D,OAAO,EAAE,0BAA0B,EAAE,MAAM,cAAc,CAAA;AACzD,OAAO,EAAE,sBAAsB,EAAE,MAAM,kCAAkC,CAAA;AACzE,OAAO,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,0BAA0B,EAC1B,+BAA+B,EAC/B,kBAAkB,EAClB,cAAc,GACf,MAAM,cAAc,CAAA;AACrB,YAAY,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAA;AACzE,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAA;AAC/C,OAAO,EAAE,sBAAsB,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAA;AAC1E,YAAY,EACV,0BAA0B,EAC1B,yBAAyB,EACzB,oBAAoB,EACpB,4BAA4B,EAC5B,mBAAmB,GACpB,MAAM,iBAAiB,CAAA;AACxB,OAAO,EACL,aAAa,EACb,oBAAoB,EACpB,8BAA8B,EAC9B,0BAA0B,EAC1B,4BAA4B,EAC5B,eAAe,EACf,uBAAuB,EACvB,oBAAoB,EACpB,gBAAgB,EAChB,aAAa,EACb,WAAW,EACX,SAAS,EACT,kBAAkB,EAClB,oBAAoB,EACpB,4BAA4B,EAC5B,oBAAoB,EACpB,wBAAwB,EACxB,gCAAgC,EAChC,yBAAyB,EACzB,kBAAkB,EAClB,oBAAoB,EACpB,kBAAkB,EAClB,mBAAmB,EACnB,wBAAwB,EACxB,wBAAwB,EACxB,kBAAkB,EAClB,mBAAmB,EACnB,wBAAwB,EACxB,UAAU,EACV,iBAAiB,EACjB,cAAc,EACd,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,iCAAiC,CAAA;AACxC,YAAY,EACV,YAAY,EACZ,SAAS,EACT,kBAAkB,EAClB,oBAAoB,EACpB,mBAAmB,EACnB,qBAAqB,EACrB,yBAAyB,EACzB,sBAAsB,EACtB,sBAAsB,EACtB,mBAAmB,EACnB,uBAAuB,EACvB,UAAU,EACV,iBAAiB,EACjB,uBAAuB,EACvB,oBAAoB,EACpB,wBAAwB,EACxB,0BAA0B,EAC1B,uBAAuB,GACxB,MAAM,iCAAiC,CAAA;AACxC,YAAY,EACV,gBAAgB,EAChB,eAAe,EACf,wBAAwB,EACxB,6BAA6B,EAC7B,6BAA6B,EAC7B,2BAA2B,EAC3B,uBAAuB,EACvB,6BAA6B,EAC7B,4BAA4B,EAC5B,wBAAwB,EACxB,mBAAmB,EACnB,sBAAsB,EACtB,uBAAuB,GACxB,MAAM,YAAY,CAAA;AACnB,OAAO,EAAE,6BAA6B,EAAE,yBAAyB,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAA;AACtH,OAAO,EACL,wBAAwB,EACxB,iCAAiC,EACjC,+BAA+B,GAChC,MAAM,eAAe,CAAA;AACtB,OAAO,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,0BAA0B,CAAA;AAC/D,OAAO,EAAE,YAAY,EAAE,MAAM,qCAAqC,CAAA;AAClE,OAAO,EAAE,0BAA0B,EAAE,MAAM,cAAc,CAAA;AACzD,OAAO,EAAE,sBAAsB,EAAE,MAAM,kCAAkC,CAAA;AACzE,OAAO,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAA"}

package/dist/index.js

@@ -1,10 +1,11 @@
 export { DEFAULT_ACHIEVEMENT_METRIC, DEFAULT_ACHIEVEMENT_METRIC_SLUG, ENGINE_EVENT_TYPES, ENGINE_METRICS, } from './catalog.js';
 export { achievementPlugin } from './plugin.js';
 export { seedAchievementCatalog, seedAchievements } from './seed/index.js';
-export { evaluateRules, evaluateRuleProgress, collectAchievementCompleteRefs, buildCatalogProgressGroups, getUserProgress, getMetricLeaderboard, grantAchievement, loadMetricDoc, recordEvent, recordLog, recordMetricChange, rebuildMetricBalance, rebuildMetricBalancesForUser, reconcileProgression, reconcileUserProgression, releasePendingAchievementReviews, releasePendingTierReviews, resolveCurrentTier, resolveElapsedAnchor, resolveMetricValue, resolveTierProgress, reviewAchievementRequest, submitAchievementRequest, syncTierChangedLog, syncTierProgression, syncCompositeProgression, catalogRef, transitionLogData, transitionToId, validateRuleGroup, validateRuleNode, } from './services/achievement/index.js';
+export { evaluateRules, evaluateRuleProgress, collectAchievementCompleteRefs, buildCatalogProgressGroups, buildUnlockRequirementLeaves, getUserProgress, loadUserProgressReviews, getMetricLeaderboard, grantAchievement, loadMetricDoc, recordEvent, recordLog, recordMetricChange, rebuildMetricBalance, rebuildMetricBalancesForUser, reconcileProgression, reconcileUserProgression, releasePendingAchievementReviews, releasePendingTierReviews, resolveCurrentTier, resolveElapsedAnchor, resolveMetricValue, resolveTierProgress, reviewAchievementRequest, submitAchievementRequest, syncTierChangedLog, syncTierProgression, syncCompositeProgression, catalogRef, transitionLogData, transitionToId, validateRuleGroup, validateRuleNode, } from './services/achievement/index.js';
 export { DEFAULT_COLLECTION_BASE_SLUGS, DEFAULT_COLLECTION_PREFIX, DEFAULT_ADMIN_GROUP } from './collections/slugs.js';
 export { DEFAULT_ME_ENDPOINT_PATH, DEFAULT_LEADERBOARD_ENDPOINT_PATH, DEFAULT_RECONCILE_ENDPOINT_PATH, } from './defaults.js';
 export { collectionOf, slugOf } from './collections/helpers.js';
+export { eachRuleLeaf } from './collections/hooks/eachRuleLeaf.js';
 export { isAchievementPluginEnabled } from './enabled.js';
 export { descriptionToPlaintext } from './fields/descriptionPlaintext.js';
 export { plainTextToLexical } from './fields/plainTextToLexical.js';

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

@@ -0,0 +1,48 @@
+import type { Payload, PayloadRequest } from 'payload';
+export declare const UNLOCK_REQUIREMENT_RELATION_FIELDS: {
+    readonly tier: "tiers";
+    readonly achievement: "achievements";
+    readonly metric: "metrics";
+    readonly eventType: "eventTypes";
+};
+export type UnlockRequirementCollectionKey = (typeof UNLOCK_REQUIREMENT_RELATION_FIELDS)[keyof typeof UNLOCK_REQUIREMENT_RELATION_FIELDS];
+export type UnlockRequirementRelation = {
+    field: keyof typeof UNLOCK_REQUIREMENT_RELATION_FIELDS;
+    collectionKey: UnlockRequirementCollectionKey;
+    id?: string;
+    slug?: string;
+    name?: string;
+};
+/**
+ * Structured unlock/eligibility leaf — catalog names only, no host UI copy.
+ * Hosts format `label` / `detail` from these fields.
+ */
+export type UnlockRequirementLeaf = {
+    id: string;
+    type: string;
+    met: boolean;
+    /** 0..1 from {@link evaluateRuleProgress}. */
+    progress: number;
+    relations: UnlockRequirementRelation[];
+    target?: number;
+    unit?: string;
+    since?: string;
+};
+/**
+ * Walk every leaf in a rule tree, evaluate met/progress, and return catalog-backed
+ * subjects. Payload rows often carry empty `rules: []` + default combinator — those
+ * are still leaves ({@link eachRuleLeaf}).
+ *
+ * `achievement-complete` is omitted by default so hosts can keep those on catalog groups.
+ */
+export declare function buildUnlockRequirementLeaves(args: {
+    payload: Payload;
+    req?: PayloadRequest;
+    userId: string;
+    scopeId: string | null;
+    rules: unknown;
+    ladderRank?: number | null;
+    locale?: string;
+    includeAchievementComplete?: boolean;
+}): Promise<UnlockRequirementLeaf[]>;
+//# sourceMappingURL=buildUnlockRequirementLeaves.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"buildUnlockRequirementLeaves.d.ts","sourceRoot":"","sources":["../../../src/services/achievement/buildUnlockRequirementLeaves.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,SAAS,CAAA;AAOtD,eAAO,MAAM,kCAAkC;;;;;CAKyC,CAAA;AAExF,MAAM,MAAM,8BAA8B,GACxC,CAAC,OAAO,kCAAkC,CAAC,CAAC,MAAM,OAAO,kCAAkC,CAAC,CAAA;AAE9F,MAAM,MAAM,yBAAyB,GAAG;IACtC,KAAK,EAAE,MAAM,OAAO,kCAAkC,CAAA;IACtD,aAAa,EAAE,8BAA8B,CAAA;IAC7C,EAAE,CAAC,EAAE,MAAM,CAAA;IACX,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,MAAM,CAAA;CACd,CAAA;AAED;;;GAGG;AACH,MAAM,MAAM,qBAAqB,GAAG;IAClC,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,MAAM,CAAA;IACZ,GAAG,EAAE,OAAO,CAAA;IACZ,8CAA8C;IAC9C,QAAQ,EAAE,MAAM,CAAA;IAChB,SAAS,EAAE,yBAAyB,EAAE,CAAA;IACtC,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,KAAK,CAAC,EAAE,MAAM,CAAA;CACf,CAAA;AAqHD;;;;;;GAMG;AACH,wBAAsB,4BAA4B,CAAC,IAAI,EAAE;IACvD,OAAO,EAAE,OAAO,CAAA;IAChB,GAAG,CAAC,EAAE,cAAc,CAAA;IACpB,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB,KAAK,EAAE,OAAO,CAAA;IACd,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC1B,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,0BAA0B,CAAC,EAAE,OAAO,CAAA;CACrC,GAAG,OAAO,CAAC,qBAAqB,EAAE,CAAC,CA8EnC"}

package/dist/services/achievement/buildUnlockRequirementLeaves.js

@@ -0,0 +1,192 @@
+import { eachRuleLeaf } from '../../collections/hooks/eachRuleLeaf.js';
+import { collectionOf } from '../../collections/helpers.js';
+import { evaluateRuleProgress, evaluateRules } from './evaluateRules.js';
+import { relationId } from './relationId.js';
+export const UNLOCK_REQUIREMENT_RELATION_FIELDS = {
+    tier: 'tiers',
+    achievement: 'achievements',
+    metric: 'metrics',
+    eventType: 'eventTypes',
+};
+function relationName(value) {
+    if (value && typeof value === 'object' && 'name' in value) {
+        const name = value.name;
+        if (typeof name === 'string' && name)
+            return name;
+    }
+    return null;
+}
+function relationSlug(value) {
+    if (value && typeof value === 'object' && 'slug' in value) {
+        const slug = value.slug;
+        if (typeof slug === 'string' && slug)
+            return slug;
+    }
+    return null;
+}
+function slugField(rule, relationKey) {
+    const raw = rule[`${relationKey}Slug`];
+    return typeof raw === 'string' && raw ? raw : null;
+}
+function numericTarget(rule) {
+    for (const key of ['amount', 'minimum', 'count']) {
+        const value = rule[key];
+        if (typeof value === 'number' && Number.isFinite(value) && value >= 0)
+            return value;
+    }
+    return null;
+}
+async function resolveCatalogName(args) {
+    const named = relationName(args.value);
+    const slug = args.slug || relationSlug(args.value);
+    const id = relationId(args.value);
+    if (named) {
+        return {
+            ...(id ? { id } : {}),
+            ...(slug ? { slug } : {}),
+            name: named,
+        };
+    }
+    if (slug) {
+        const cached = args.cache.get(`slug:${args.collectionKey}:${slug}`);
+        if (cached)
+            return { ...(id ? { id } : {}), slug, name: cached };
+    }
+    if (id) {
+        const cached = args.cache.get(`id:${args.collectionKey}:${id}`);
+        if (cached) {
+            return { id, ...(slug ? { slug } : {}), name: cached };
+        }
+        try {
+            const doc = (await args.payload.findByID({
+                collection: collectionOf(args.collectionKey),
+                id,
+                depth: 0,
+                overrideAccess: true,
+                req: args.req,
+                ...(args.locale ? { locale: args.locale } : {}),
+            }));
+            const name = (typeof doc?.name === 'string' && doc.name) ||
+                (typeof doc?.slug === 'string' && doc.slug) ||
+                null;
+            if (name) {
+                args.cache.set(`id:${args.collectionKey}:${id}`, name);
+                if (doc?.slug)
+                    args.cache.set(`slug:${args.collectionKey}:${doc.slug}`, name);
+                return { id, ...(doc?.slug ? { slug: doc.slug } : slug ? { slug } : {}), name };
+            }
+        }
+        catch {
+            /* fall through */
+        }
+    }
+    if (slug && !id) {
+        try {
+            const found = await args.payload.find({
+                collection: collectionOf(args.collectionKey),
+                depth: 0,
+                limit: 1,
+                overrideAccess: true,
+                req: args.req,
+                where: { slug: { equals: slug } },
+                ...(args.locale ? { locale: args.locale } : {}),
+            });
+            const doc = found.docs[0];
+            const resolvedId = relationId(doc);
+            const name = (typeof doc?.name === 'string' && doc.name) ||
+                (typeof doc?.slug === 'string' && doc.slug) ||
+                slug;
+            if (resolvedId)
+                args.cache.set(`id:${args.collectionKey}:${resolvedId}`, name);
+            args.cache.set(`slug:${args.collectionKey}:${slug}`, name);
+            return { ...(resolvedId ? { id: resolvedId } : {}), slug, name };
+        }
+        catch {
+            /* fall through */
+        }
+    }
+    return {
+        ...(id ? { id } : {}),
+        ...(slug ? { slug } : {}),
+        ...(slug || id ? { name: slug || id || undefined } : {}),
+    };
+}
+/**
+ * Walk every leaf in a rule tree, evaluate met/progress, and return catalog-backed
+ * subjects. Payload rows often carry empty `rules: []` + default combinator — those
+ * are still leaves ({@link eachRuleLeaf}).
+ *
+ * `achievement-complete` is omitted by default so hosts can keep those on catalog groups.
+ */
+export async function buildUnlockRequirementLeaves(args) {
+    const req = args.req ?? { payload: args.payload };
+    const cache = new Map();
+    const leaves = [];
+    eachRuleLeaf(args.rules, (rule) => {
+        const type = String(rule.type ?? '');
+        if (!type)
+            return;
+        if (type === 'achievement-complete' && !args.includeAchievementComplete)
+            return;
+        leaves.push(rule);
+    });
+    const out = [];
+    for (let index = 0; index < leaves.length; index += 1) {
+        const rule = leaves[index];
+        const type = String(rule.type);
+        const leafRules = [rule];
+        const met = await evaluateRules({
+            payload: args.payload,
+            req,
+            rules: leafRules,
+            userId: args.userId,
+            scopeId: args.scopeId,
+            ladderRank: args.ladderRank,
+        });
+        const progress = await evaluateRuleProgress({
+            payload: args.payload,
+            req,
+            rules: leafRules,
+            userId: args.userId,
+            scopeId: args.scopeId,
+            ladderRank: args.ladderRank,
+        });
+        const relations = [];
+        for (const [field, collectionKey] of Object.entries(UNLOCK_REQUIREMENT_RELATION_FIELDS)) {
+            const key = field;
+            if (rule[key] == null && !slugField(rule, key))
+                continue;
+            const resolved = await resolveCatalogName({
+                payload: args.payload,
+                req,
+                locale: args.locale,
+                collectionKey,
+                value: rule[key],
+                slug: slugField(rule, key),
+                cache,
+            });
+            if (!resolved.id && !resolved.slug && !resolved.name)
+                continue;
+            relations.push({ field: key, collectionKey, ...resolved });
+        }
+        const target = numericTarget(rule);
+        const unit = typeof rule.unit === 'string' && rule.unit ? rule.unit : undefined;
+        // `since` / `unit` only matter when a duration/count target is set (defaults pollute other leaves).
+        const since = target != null && typeof rule.since === 'string' && rule.since ? rule.since : undefined;
+        const subjectKey = relations
+            .map((row) => row.name || row.slug || row.id)
+            .filter(Boolean)
+            .join(':') || 'leaf';
+        out.push({
+            id: `${type}:${index}:${subjectKey}`,
+            type,
+            met,
+            progress,
+            relations,
+            ...(target != null ? { target } : {}),
+            ...(unit ? { unit } : {}),
+            ...(since ? { since } : {}),
+        });
+    }
+    return out;
+}

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

@@ -1,4 +1,5 @@
 import type { PaginatedDocs, Payload, PayloadRequest } from 'payload';
+import { type UserProgressReviews } from './loadUserProgressReviews.js';
 /** Catalog slice — `description` matches the collection (Lexical JSON, or legacy string). */
 type LeanCatalog = {
     id: string;
@@ -32,10 +33,15 @@ declare function leanRequest(doc: Record<string, unknown>): {
     updatedAt: {} | null;
     createdAt: {} | null;
 };
+export type GetUserProgressInclude = {
+    /** Pending achievement keys + open/rejected tier requests. */
+    reviews?: boolean;
+};
 export type UserProgressMeResponse = PaginatedDocs<ReturnType<typeof leanGrant>> & {
     /** Ladder-derived current tier(s). */
     tiers: LeanTier[];
     requests: ReturnType<typeof leanRequest>[];
+    reviews?: UserProgressReviews;
 };
 /**
  * Current-user snapshot. Top-level Payload `find` shape for **grants**;
@@ -49,6 +55,7 @@ export declare function getUserProgress(args: {
     paging?: GetUserProgressPaging;
     /** Content locale for localized achievement / tier names (falls back to `req.locale`). */
     locale?: string;
+    include?: GetUserProgressInclude;
 }): Promise<UserProgressMeResponse>;
 export {};
 //# sourceMappingURL=getUserProgress.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"getUserProgress.d.ts","sourceRoot":"","sources":["../../../src/services/achievement/getUserProgress.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,SAAS,CAAA;AAOrE,6FAA6F;AAC7F,KAAK,WAAW,GAAG;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,OAAO,CAAA;CAAE,CAAA;AACtF,KAAK,QAAQ,GAAG,WAAW,GAAG;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAAA;AAExE,MAAM,MAAM,qBAAqB,GAAG;IAClC,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,aAAa,CAAC,EAAE,MAAM,CAAA;CACvB,CAAA;AAmBD,iBAAS,SAAS,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;;;;;;;;EAU9C;AAED,iBAAS,WAAW,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;;;;;;;EAShD;AAoBD,MAAM,MAAM,sBAAsB,GAAG,aAAa,CAAC,UAAU,CAAC,OAAO,SAAS,CAAC,CAAC,GAAG;IACjF,sCAAsC;IACtC,KAAK,EAAE,QAAQ,EAAE,CAAA;IACjB,QAAQ,EAAE,UAAU,CAAC,OAAO,WAAW,CAAC,EAAE,CAAA;CAC3C,CAAA;AAkED;;;GAGG;AACH,wBAAsB,eAAe,CAAC,IAAI,EAAE;IAC1C,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,qBAAqB,CAAA;IAC9B,0FAA0F;IAC1F,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAiDlC"}
+{"version":3,"file":"getUserProgress.d.ts","sourceRoot":"","sources":["../../../src/services/achievement/getUserProgress.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,SAAS,CAAA;AAGrE,OAAO,EAA2B,KAAK,mBAAmB,EAAE,MAAM,8BAA8B,CAAA;AAKhG,6FAA6F;AAC7F,KAAK,WAAW,GAAG;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,OAAO,CAAA;CAAE,CAAA;AACtF,KAAK,QAAQ,GAAG,WAAW,GAAG;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAAA;AAExE,MAAM,MAAM,qBAAqB,GAAG;IAClC,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,aAAa,CAAC,EAAE,MAAM,CAAA;CACvB,CAAA;AAmBD,iBAAS,SAAS,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;;;;;;;;EAU9C;AAED,iBAAS,WAAW,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;;;;;;;EAShD;AAoBD,MAAM,MAAM,sBAAsB,GAAG;IACnC,8DAA8D;IAC9D,OAAO,CAAC,EAAE,OAAO,CAAA;CAClB,CAAA;AAED,MAAM,MAAM,sBAAsB,GAAG,aAAa,CAAC,UAAU,CAAC,OAAO,SAAS,CAAC,CAAC,GAAG;IACjF,sCAAsC;IACtC,KAAK,EAAE,QAAQ,EAAE,CAAA;IACjB,QAAQ,EAAE,UAAU,CAAC,OAAO,WAAW,CAAC,EAAE,CAAA;IAC1C,OAAO,CAAC,EAAE,mBAAmB,CAAA;CAC9B,CAAA;AAkED;;;GAGG;AACH,wBAAsB,eAAe,CAAC,IAAI,EAAE;IAC1C,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,qBAAqB,CAAA;IAC9B,0FAA0F;IAC1F,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,OAAO,CAAC,EAAE,sBAAsB,CAAA;CACjC,GAAG,OAAO,CAAC,sBAAsB,CAAC,CA0DlC"}

package/dist/services/achievement/getUserProgress.js

@@ -1,4 +1,5 @@
 import { collectionOf } from '../../collections/helpers.js';
+import { loadUserProgressReviews } from './loadUserProgressReviews.js';
 import { relationId } from './relationId.js';
 import { resolveCurrentTier } from './resolveCurrentTier.js';
 import { userScopeWhere } from './where.js';
@@ -125,7 +126,7 @@ export async function getUserProgress(args) {
     const page = args.paging?.page ?? 1;
     const requestsLimit = args.paging?.requestsLimit ?? 20;
     const locale = args.locale ?? (args.req?.locale || undefined);
-    const [grants, requests, tiers] = await Promise.all([
+    const [grants, requests, tiers, reviews] = await Promise.all([
         args.payload.find({
             collection: collectionOf('grants'),
             depth: 1,
@@ -155,10 +156,19 @@ export async function getUserProgress(args) {
             scopeId,
             locale,
         }),
+        args.include?.reviews
+            ? loadUserProgressReviews({
+                payload: args.payload,
+                req: args.req,
+                userId: args.userId,
+                scopeId,
+            })
+            : Promise.resolve(undefined),
     ]);
     return {
         ...mapPaginatedDocs(grants, (doc) => leanGrant(doc)),
         tiers,
         requests: requests.docs.map((doc) => leanRequest(doc)),
+        ...(reviews ? { reviews } : {}),
     };
 }

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

@@ -2,7 +2,12 @@ export { evaluateRules, evaluateRuleProgress, normalizeRuleGroup, collectAchieve
 export type { RuleGroup, AchievementCompleteRef } from './evaluateRules.js';
 export { buildCatalogProgressGroups } from './buildCatalogProgressGroups.js';
 export type { CatalogProgressGroup, CatalogProgressItem } from './buildCatalogProgressGroups.js';
+export { buildUnlockRequirementLeaves } from './buildUnlockRequirementLeaves.js';
+export type { UnlockRequirementCollectionKey, UnlockRequirementLeaf, UnlockRequirementRelation, } from './buildUnlockRequirementLeaves.js';
 export { getUserProgress } from './getUserProgress.js';
+export type { GetUserProgressInclude, GetUserProgressPaging, UserProgressMeResponse } from './getUserProgress.js';
+export { loadUserProgressReviews } from './loadUserProgressReviews.js';
+export type { UserProgressReviews, UserProgressTierRequest } from './loadUserProgressReviews.js';
 export { getMetricLeaderboard } from './getMetricLeaderboard.js';
 export type { MetricLeaderboardResult, MetricLeaderboardRow } from './getMetricLeaderboard.js';
 export { applyMetricBalanceDelta, findMetricBalance, metricBalanceKey, rebuildMetricBalance, rebuildMetricBalancesForUser, } from './metricBalances.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,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"}
+{"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,4BAA4B,EAAE,MAAM,mCAAmC,CAAA;AAChF,YAAY,EACV,8BAA8B,EAC9B,qBAAqB,EACrB,yBAAyB,GAC1B,MAAM,mCAAmC,CAAA;AAC1C,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AACtD,YAAY,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAA;AACjH,OAAO,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAA;AACtE,YAAY,EAAE,mBAAmB,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAA;AAChG,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,8 @@
 export { evaluateRules, evaluateRuleProgress, normalizeRuleGroup, collectAchievementCompleteRefs } from './evaluateRules.js';
 export { buildCatalogProgressGroups } from './buildCatalogProgressGroups.js';
+export { buildUnlockRequirementLeaves } from './buildUnlockRequirementLeaves.js';
 export { getUserProgress } from './getUserProgress.js';
+export { loadUserProgressReviews } from './loadUserProgressReviews.js';
 export { getMetricLeaderboard } from './getMetricLeaderboard.js';
 export { applyMetricBalanceDelta, findMetricBalance, metricBalanceKey, rebuildMetricBalance, rebuildMetricBalancesForUser, } from './metricBalances.js';
 export { resolveMetricValue, loadMetricDoc } from './resolveMetricValue.js';

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

@@ -0,0 +1,23 @@
+import type { Payload, PayloadRequest } from 'payload';
+export type UserProgressTierRequest = {
+    id: string;
+    status: 'pending' | 'rejected';
+    tierId: string | null;
+};
+export type UserProgressReviews = {
+    /** Achievement definition ids and slugs with a pending request. */
+    pendingAchievementKeys: string[];
+    /** Open or rejected tier requests (host decides which badge wins). */
+    tierRequests: UserProgressTierRequest[];
+};
+/**
+ * Review-queue snapshot for member UI (pending achievement keys + open/rejected tier requests).
+ * Does not decide ready/rejected presentation — hosts apply ladder context themselves.
+ */
+export declare function loadUserProgressReviews(args: {
+    payload: Payload;
+    req?: PayloadRequest;
+    userId: string;
+    scopeId?: string | null;
+}): Promise<UserProgressReviews>;
+//# sourceMappingURL=loadUserProgressReviews.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"loadUserProgressReviews.d.ts","sourceRoot":"","sources":["../../../src/services/achievement/loadUserProgressReviews.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,cAAc,EAAS,MAAM,SAAS,CAAA;AAQ7D,MAAM,MAAM,uBAAuB,GAAG;IACpC,EAAE,EAAE,MAAM,CAAA;IACV,MAAM,EAAE,SAAS,GAAG,UAAU,CAAA;IAC9B,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;CACtB,CAAA;AAED,MAAM,MAAM,mBAAmB,GAAG;IAChC,mEAAmE;IACnE,sBAAsB,EAAE,MAAM,EAAE,CAAA;IAChC,sEAAsE;IACtE,YAAY,EAAE,uBAAuB,EAAE,CAAA;CACxC,CAAA;AAyBD;;;GAGG;AACH,wBAAsB,uBAAuB,CAAC,IAAI,EAAE;IAClD,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,mBAAmB,CAAC,CA+C/B"}

package/dist/services/achievement/loadUserProgressReviews.js

@@ -0,0 +1,79 @@
+import { collectionOf } from '../../collections/helpers.js';
+import { relationId } from './relationId.js';
+const PENDING_ACHIEVEMENT_REQUESTS_LIMIT = 200;
+const TIER_REQUESTS_LIMIT = 50;
+function relationSlug(value) {
+    if (value && typeof value === 'object' && 'slug' in value) {
+        const slug = value.slug;
+        if (typeof slug === 'string' && slug)
+            return slug;
+    }
+    return null;
+}
+function pendingAchievementWhere(userId, scopeId) {
+    const clauses = [{ user: { equals: userId } }, { status: { equals: 'pending' } }];
+    if (scopeId)
+        clauses.push({ scope: { equals: scopeId } });
+    return { and: clauses };
+}
+function openOrRejectedTierRequestWhere(userId, scopeId) {
+    const clauses = [
+        { user: { equals: userId } },
+        { status: { in: ['pending', 'rejected'] } },
+    ];
+    if (scopeId)
+        clauses.push({ scope: { equals: scopeId } });
+    return { and: clauses };
+}
+/**
+ * Review-queue snapshot for member UI (pending achievement keys + open/rejected tier requests).
+ * Does not decide ready/rejected presentation — hosts apply ladder context themselves.
+ */
+export async function loadUserProgressReviews(args) {
+    const scopeId = args.scopeId ?? null;
+    const [pendingAchievementRequests, tierRequests] = await Promise.all([
+        args.payload.find({
+            collection: collectionOf('achievementRequests'),
+            depth: 1,
+            limit: PENDING_ACHIEVEMENT_REQUESTS_LIMIT,
+            pagination: false,
+            overrideAccess: true,
+            req: args.req,
+            where: pendingAchievementWhere(args.userId, scopeId),
+        }),
+        scopeId
+            ? args.payload.find({
+                collection: collectionOf('tierRequests'),
+                depth: 0,
+                limit: TIER_REQUESTS_LIMIT,
+                pagination: false,
+                overrideAccess: true,
+                req: args.req,
+                where: openOrRejectedTierRequestWhere(args.userId, scopeId),
+            })
+            : Promise.resolve({ docs: [] }),
+    ]);
+    const pendingAchievementKeys = new Set();
+    for (const doc of pendingAchievementRequests.docs) {
+        const id = relationId(doc.achievement);
+        const slug = relationSlug(doc.achievement);
+        if (id)
+            pendingAchievementKeys.add(id);
+        if (slug)
+            pendingAchievementKeys.add(slug);
+    }
+    const reviews = [];
+    for (const doc of tierRequests.docs) {
+        const status = doc.status === 'rejected' ? 'rejected' : doc.status === 'pending' ? 'pending' : null;
+        if (!status)
+            continue;
+        const id = typeof doc.id === 'string' && doc.id ? doc.id : relationId(doc.id);
+        if (!id)
+            continue;
+        reviews.push({ id, status, tierId: relationId(doc.tier) });
+    }
+    return {
+        pendingAchievementKeys: [...pendingAchievementKeys],
+        tierRequests: reviews,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dappermountain/payload-plugin-achievements",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "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",