@dappermountain/payload-plugin-achievements 0.1.0 → 0.2.0

package/README.md

@@ -22,11 +22,14 @@ Most gamification features end up as one-off collections and scattered hooks. Th
 
 ## Install
 
+Preferred package manager: **Bun**.
+
 ```bash
-npm install @dappermountain/payload-plugin-achievements
-# or: pnpm add / yarn add / bun add
+bun add @dappermountain/payload-plugin-achievements
 ```
 
+Other clients also work (`npm install @dappermountain/payload-plugin-achievements`, etc.).
+
 ## Quick start
 
 ```ts
@@ -80,7 +83,8 @@ Slugs are prefixed with `achievement-` by default so they don’t collide with y
 | `achievements` | `achievement-definitions` | Things a user can earn (with eligibility / completion rules). |
 | `grants` | `achievement-grants` | One row per earned achievement per user (+ scope). |
 | `achievementRequests` | `achievement-requests` | Request → pending / approved / rejected. |
-| `logs` | `achievement-logs` | Append-only history of what happened. |
+| `tierRequests` | `achievement-tier-requests` | Tier unlock awaiting review (when the tier has `requiresReview`). |
+| `logs` | `achievement-logs` | Member activity history (grants, revokes, tier moves, metrics, custom events). |
 
 **System catalog rows** (seeded by `seedAchievementCatalog`) are protected from deletion and slug changes:
 
@@ -89,6 +93,7 @@ Slugs are prefixed with `achievement-` by default so they don’t collide with y
 | `points` | Default metric |
 | `metric.delta` | Metric change log type (requires metric + change amount) |
 | `achievement.granted` | Written when a grant is created |
+| `achievement.revoked` | Written when a grant is deleted |
 | `tier.changed` | Written when derived tier moves |
 
 Event types can require an **actor** and/or a **metric + change**. Admin only prompts for those fields when the type needs them.
@@ -102,7 +107,7 @@ Unlock (tiers), eligibility, and completion (achievements) share the same rule t
 - Built-in leaves → `tier-at-least`, `achievement-complete`, `metric-minimum`, `event-count`
 - Custom leaves → register via `extensions.ruleTypes`
 
-**Current tier** is computed by walking tiers in `rank` order and evaluating each tier’s unlock rules (`resolveCurrentTier`). **Next-tier fill** uses fractional progress on the same trees (`resolveTierProgress` / `evaluateRuleProgress`):
+**Current tier** is computed by walking tiers in `rank` order and evaluating each tier’s unlock rules (`resolveCurrentTier`). Tiers with **`requiresReview`** only become current after an **approved tier request**. **Next-tier fill** uses fractional progress on the same trees (`resolveTierProgress` / `evaluateRuleProgress`):
 
 | Combinator / leaf | Progress behavior |
 | --- | --- |
@@ -241,6 +246,8 @@ import {
   recordLog,
   recordMetricChange,
   grantAchievement,
+  reconcileProgression,
+  reconcileUserProgression,
   resolveCurrentTier,
   resolveTierProgress,
   getUserProgress,
@@ -251,19 +258,26 @@ import {
 await recordLog({ payload, userId, scopeId, type: 'host.custom-kind', actorId })
 await recordMetricChange({ payload, userId, scopeId, metric: 'points', change: 10 })
 const tier = await resolveCurrentTier({ payload, userId, scopeId })
+
+// Repair users whose grants predate side-effect hooks (idempotent)
+await reconcileProgression({ payload })
 ```
 
-Pass catalog **slugs** (or ids) for `type` and `metric`. Metric totals are the sum of `change` on matching logs. Recording metrics or granting achievements may append a `tier.changed` log when the derived ladder moves.
+Pass catalog **slugs** (or ids) for `type` and `metric`. Metric totals are the sum of `change` on matching logs. Creating or deleting **grants** (Admin or API) writes `achievement.granted` / `achievement.revoked`, syncs composed achievements, and may open tier requests / write `tier.changed`.
+
+**Admin:** Grants list includes **Repair progression**, which `POST`s the reconcile endpoint (requires `canReview`).
 
 ## REST surface
 
 | Goal | Request |
 | --- | --- |
 | Current user snapshot | `GET /api/achievements/me?scope=<scopeId>&limit=10&page=1` |
+| Repair progression | `POST /api/achievements/reconcile` (reviewer; optional `{ userId, scopeId, limit }`) |
 | List grants | `GET /api/achievement-grants?where[user][equals]=<userId>` |
 | Log history | `GET /api/achievement-logs?where[user][equals]=<userId>` |
 | Request an achievement | `POST /api/achievement-requests` with `{ achievement }` |
-| Approve / reject | `PATCH /api/achievement-requests/:id` with `{ status: "approved" \| "rejected" }` |
+| Approve / reject achievement | `PATCH /api/achievement-requests/:id` with `{ status: "approved" \| "rejected" }` |
+| Approve / reject tier | `PATCH /api/achievement-tier-requests/:id` with `{ status: "approved" \| "rejected" }` |
 | Browse catalogs | `GET /api/achievement-event-types`, `GET /api/achievement-metrics`, … |
 
 Exact collection paths follow your `collections.prefix` / `slugs` settings.

package/dist/admin/ReconcileProgressionButton.d.ts

@@ -0,0 +1,11 @@
+import React from 'react';
+type ReconcileProgressionButtonProps = {
+    /** Absolute API path including `/api` prefix, e.g. `/api/achievements/reconcile`. */
+    reconcilePath: string;
+};
+/**
+ * Grants list control — runs progression reconcile for all users with grants.
+ */
+export declare function ReconcileProgressionButton(props: ReconcileProgressionButtonProps): React.JSX.Element;
+export {};
+//# sourceMappingURL=ReconcileProgressionButton.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ReconcileProgressionButton.d.ts","sourceRoot":"","sources":["../../src/admin/ReconcileProgressionButton.tsx"],"names":[],"mappings":"AAGA,OAAO,KAAgC,MAAM,OAAO,CAAA;AAEpD,KAAK,+BAA+B,GAAG;IACrC,qFAAqF;IACrF,aAAa,EAAE,MAAM,CAAA;CACtB,CAAA;AAED;;GAEG;AACH,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,+BAA+B,qBAoDhF"}

package/dist/admin/ReconcileProgressionButton.js

@@ -0,0 +1,41 @@
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Button, toast, useConfig } from '@payloadcms/ui';
+import { useCallback, useState } from 'react';
+/**
+ * Grants list control — runs progression reconcile for all users with grants.
+ */
+export function ReconcileProgressionButton(props) {
+    const { reconcilePath } = props;
+    const { config } = useConfig();
+    const [busy, setBusy] = useState(false);
+    const onClick = useCallback(async () => {
+        if (busy)
+            return;
+        setBusy(true);
+        try {
+            const serverURL = config.serverURL?.replace(/\/$/, '') ?? '';
+            const url = `${serverURL}${reconcilePath.startsWith('/') ? reconcilePath : `/${reconcilePath}`}`;
+            const res = await fetch(url, {
+                method: 'POST',
+                credentials: 'include',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({}),
+            });
+            const json = (await res.json().catch(() => null));
+            if (!res.ok) {
+                const message = json?.errors?.[0]?.message ?? `Request failed (${res.status})`;
+                toast.error(message);
+                return;
+            }
+            toast.success(`Repair complete — users ${json?.usersScanned ?? 0}, grants ${json?.compositesGranted ?? 0}, logs ${json?.grantedLogsBackfilled ?? 0}, requests ${json?.achievementRequestsEnsured ?? 0}, tier requests ${json?.tierRequestsEnsured ?? 0}`);
+        }
+        catch (error) {
+            toast.error(error instanceof Error ? error.message : 'Repair failed');
+        }
+        finally {
+            setBusy(false);
+        }
+    }, [busy, config.serverURL, reconcilePath]);
+    return (_jsx("div", { style: { marginBottom: '1rem' }, children: _jsx(Button, { buttonStyle: "secondary", disabled: busy, onClick: () => void onClick(), children: busy ? 'Repairing…' : 'Repair progression' }) }));
+}

package/dist/catalog.d.ts

@@ -1,6 +1,9 @@
 export declare const ENGINE_EVENT_TYPES: readonly [{
     readonly slug: "achievement.granted";
     readonly name: "Achievement granted";
+}, {
+    readonly slug: "achievement.revoked";
+    readonly name: "Achievement revoked";
 }, {
     readonly slug: "metric.delta";
     readonly name: "Metric delta";

package/dist/catalog.d.ts.map

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

package/dist/catalog.js

@@ -1,5 +1,6 @@
 export const ENGINE_EVENT_TYPES = [
     { slug: 'achievement.granted', name: 'Achievement granted' },
+    { slug: 'achievement.revoked', name: 'Achievement revoked' },
     { slug: 'metric.delta', name: 'Metric delta', requiresMetric: true },
     { slug: 'tier.changed', name: 'Tier changed' },
 ];

package/dist/collections/AchievementRequests/hooks/prepareAchievementRequest.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"prepareAchievementRequest.d.ts","sourceRoot":"","sources":["../../../../src/collections/AchievementRequests/hooks/prepareAchievementRequest.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,yBAAyB,EACzB,4BAA4B,EAE7B,MAAM,SAAS,CAAA;AA0ChB;;;;GAIG;AACH,eAAO,MAAM,yBAAyB,EAAE,4BAqDvC,CAAA;AAED;;GAEG;AACH,eAAO,MAAM,sBAAsB,EAAE,yBAsCpC,CAAA"}
+{"version":3,"file":"prepareAchievementRequest.d.ts","sourceRoot":"","sources":["../../../../src/collections/AchievementRequests/hooks/prepareAchievementRequest.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,yBAAyB,EACzB,4BAA4B,EAE7B,MAAM,SAAS,CAAA;AA2ChB;;;;GAIG;AACH,eAAO,MAAM,yBAAyB,EAAE,4BAqEvC,CAAA;AAED;;GAEG;AACH,eAAO,MAAM,sBAAsB,EAAE,yBAsCpC,CAAA"}

package/dist/collections/AchievementRequests/hooks/prepareAchievementRequest.js

@@ -1,5 +1,6 @@
 import { APIError } from 'payload';
 import { collectionOf } from '../../../collections/helpers';
+import { CTX_SYSTEM_REQUEST } from '../../../services/achievement/contextFlags';
 import { evaluateRules, ruleGroupHasProgressRequirements } from '../../../services/achievement/evaluateRules';
 import { grantAchievement } from '../../../services/achievement/submitAchievementRequest';
 import { relationId } from '../../../services/achievement/relationId';
@@ -34,30 +35,49 @@ export const prepareAchievementRequest = async ({ data, operation, req, original
     if (!data)
         return data;
     if (operation === 'create') {
-        const userId = req.user?.id;
-        if (typeof userId !== 'string')
-            throw new APIError('Unauthorized', 401);
-        data.user = userId;
+        const system = Boolean(req.context?.[CTX_SYSTEM_REQUEST]);
+        if (!system) {
+            const userId = req.user?.id;
+            if (typeof userId !== 'string')
+                throw new APIError('Unauthorized', 401);
+            data.user = userId;
+        }
+        else {
+            const bound = relationId(data.user);
+            if (!bound)
+                throw new APIError('user required', 400);
+            data.user = bound;
+        }
+        const userId = relationId(data.user);
+        if (!userId)
+            throw new APIError('user required', 400);
         const scopeId = scopeIdOf(data);
         const achievement = await resolveAchievement({
             req,
             data: data,
         });
         data.achievement = achievement.id;
-        if (ruleGroupHasProgressRequirements(achievement.completionRules)) {
+        if (!system && ruleGroupHasProgressRequirements(achievement.completionRules)) {
             throw new APIError('This achievement is granted automatically when its completion rules pass.', 400);
         }
-        const eligible = await evaluateRules({
-            payload: req.payload,
-            req,
-            rules: achievement.eligibilityRules,
-            userId: userId,
-            scopeId,
-        });
-        if (!eligible) {
-            throw new APIError('Eligibility rules not met for this achievement.', 400);
+        if (!system) {
+            const eligible = await evaluateRules({
+                payload: req.payload,
+                req,
+                rules: achievement.eligibilityRules,
+                userId,
+                scopeId,
+            });
+            if (!eligible) {
+                throw new APIError('Eligibility rules not met for this achievement.', 400);
+            }
+        }
+        if (system) {
+            data.status = data.status ?? 'pending';
+        }
+        else {
+            data.status = achievement.requiresReview === false ? 'approved' : 'pending';
         }
-        data.status = achievement.requiresReview === false ? 'approved' : 'pending';
         return data;
     }
     if (operation === 'update') {

package/dist/collections/Grants/hooks/afterGrantMutation.d.ts

@@ -0,0 +1,4 @@
+import type { CollectionAfterChangeHook, CollectionAfterDeleteHook } from 'payload';
+export declare const afterGrantChange: CollectionAfterChangeHook;
+export declare const afterGrantDelete: CollectionAfterDeleteHook;
+//# sourceMappingURL=afterGrantMutation.d.ts.map

package/dist/collections/Grants/hooks/afterGrantMutation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"afterGrantMutation.d.ts","sourceRoot":"","sources":["../../../../src/collections/Grants/hooks/afterGrantMutation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,yBAAyB,EAAE,yBAAyB,EAAE,MAAM,SAAS,CAAA;AAyBnF,eAAO,MAAM,gBAAgB,EAAE,yBAmB9B,CAAA;AAED,eAAO,MAAM,gBAAgB,EAAE,yBAmB9B,CAAA"}

package/dist/collections/Grants/hooks/afterGrantMutation.js

@@ -0,0 +1,56 @@
+import { CTX_CASCADING_REVOKE, CTX_SKIP_GRANT_SIDE_EFFECTS, runAfterGrantCreated, runAfterGrantDeleted } from '../../../services/achievement/grantSideEffects';
+import { relationId } from '../../../services/achievement/relationId';
+import { collectionOf } from '../../../collections/helpers';
+async function achievementSlug(req, achievementId) {
+    try {
+        const def = (await req.payload.findByID({
+            collection: collectionOf('achievements'),
+            id: achievementId,
+            depth: 0,
+            overrideAccess: true,
+            req,
+            select: { slug: true },
+        }));
+        return def?.slug;
+    }
+    catch {
+        return undefined;
+    }
+}
+export const afterGrantChange = async ({ doc, operation, req }) => {
+    if (operation !== 'create')
+        return doc;
+    if (req.context?.[CTX_SKIP_GRANT_SIDE_EFFECTS])
+        return doc;
+    const userId = relationId(doc.user);
+    const achievementId = relationId(doc.achievement);
+    if (!userId || !achievementId)
+        return doc;
+    const scopeId = relationId(doc.scope);
+    await runAfterGrantCreated({
+        req,
+        userId,
+        achievementId,
+        scopeId,
+        achievementSlug: await achievementSlug(req, achievementId),
+    });
+    return doc;
+};
+export const afterGrantDelete = async ({ doc, req }) => {
+    if (req.context?.[CTX_SKIP_GRANT_SIDE_EFFECTS])
+        return doc;
+    const userId = relationId(doc.user);
+    const achievementId = relationId(doc.achievement);
+    if (!userId || !achievementId)
+        return doc;
+    const scopeId = relationId(doc.scope);
+    await runAfterGrantDeleted({
+        req,
+        userId,
+        achievementId,
+        scopeId,
+        achievementSlug: await achievementSlug(req, achievementId),
+        cascading: Boolean(req.context?.[CTX_CASCADING_REVOKE]),
+    });
+    return doc;
+};

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

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

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

@@ -1,7 +1,10 @@
 import { ensureUniqueGrant } from './ensureUniqueGrant';
 import { fillGrantTitle, setGrantTitle } from './setGrantTitle';
+import { afterGrantChange, afterGrantDelete } from './afterGrantMutation';
 export const hooks = {
     beforeValidate: [ensureUniqueGrant],
     beforeChange: [setGrantTitle],
     afterRead: [fillGrantTitle],
+    afterChange: [afterGrantChange],
+    afterDelete: [afterGrantDelete],
 };

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/collections/Grants/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAS,MAAM,SAAS,CAAA;AAOtD,wBAAgB,qBAAqB,IAAI,gBAAgB,CAyDxD"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/collections/Grants/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAS,MAAM,SAAS,CAAA;AAQtD,wBAAgB,qBAAqB,IAAI,gBAAgB,CA4ExD"}

package/dist/collections/Grants/index.js

@@ -1,8 +1,13 @@
 import { collectionAdmin, collectionOf, columnsWithOptionalScope, optionalFields, slugOf } from '../helpers';
 import { scopeField, userField } from '../fields';
+import { getAchievementOptions } from '../../options-store';
 import { access } from './access';
 import { hooks } from './hooks';
 export function buildGrantsCollection() {
+    const reconcilePath = getAchievementOptions().endpoints?.reconcile;
+    const apiPath = typeof reconcilePath === 'string' && reconcilePath.length > 0
+        ? `/api${reconcilePath.startsWith('/') ? reconcilePath : `/${reconcilePath}`}`
+        : null;
     return {
         slug: slugOf('grants'),
         labels: {
@@ -15,7 +20,19 @@ export function buildGrantsCollection() {
             useAsTitle: 'title',
             defaultColumns: columnsWithOptionalScope(['title', 'user', 'completedAt', 'scope']),
             listSearchableFields: ['title'],
-            description: 'What someone has earned — one row per grant. Bulk create works here.',
+            description: 'What someone has earned — one row per grant. Creating or deleting a grant updates logs and composed progression automatically.',
+            ...(apiPath
+                ? {
+                    components: {
+                        beforeListTable: [
+                            {
+                                path: '@dappermountain/payload-plugin-achievements/client#ReconcileProgressionButton',
+                                clientProps: { reconcilePath: apiPath },
+                            },
+                        ],
+                    },
+                }
+                : {}),
         }),
         fields: [
             {

package/dist/collections/Logs/index.js

@@ -20,7 +20,7 @@ export function buildLogsCollection() {
         admin: collectionAdmin({
             useAsTitle: 'id',
             defaultColumns: ['type', 'user', 'actor', 'metric', 'change', 'createdAt'],
-            description: 'A running history of what happened — grants, score changes, tier moves, and anything else you log.',
+            description: 'Member activity history — grants, revokes, score changes, tier moves, and host custom events. Not a second grant store.',
         }),
         fields: [
             ...optionalFields(scopeField()),

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

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

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

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

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

@@ -0,0 +1,8 @@
+import { isAuthenticated, requireOne } from '../../../access/index';
+import { isReviewer, isSelfUser } from '../../../access/roles/index';
+export const access = {
+    read: requireOne(isReviewer('tierRequests'), isSelfUser('user')),
+    create: isAuthenticated,
+    update: requireOne(isReviewer('tierRequests')),
+    delete: requireOne(isReviewer('tierRequests')),
+};

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

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

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

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

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

@@ -0,0 +1,5 @@
+import { afterTierRequestChange, prepareTierRequest } from './prepareTierRequest';
+export const hooks = {
+    beforeValidate: [prepareTierRequest],
+    afterChange: [afterTierRequestChange],
+};

package/dist/collections/TierRequests/hooks/prepareTierRequest.d.ts

@@ -0,0 +1,8 @@
+import type { CollectionAfterChangeHook, CollectionBeforeValidateHook } from 'payload';
+/**
+ * System-created requests (reconcile / progression sync) may set user freely.
+ * Member creates are not used for tiers in v1 — reviewers/system own the flow.
+ */
+export declare const prepareTierRequest: CollectionBeforeValidateHook;
+export declare const afterTierRequestChange: CollectionAfterChangeHook;
+//# sourceMappingURL=prepareTierRequest.d.ts.map

package/dist/collections/TierRequests/hooks/prepareTierRequest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prepareTierRequest.d.ts","sourceRoot":"","sources":["../../../../src/collections/TierRequests/hooks/prepareTierRequest.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,yBAAyB,EACzB,4BAA4B,EAE7B,MAAM,SAAS,CAAA;AAYhB;;;GAGG;AACH,eAAO,MAAM,kBAAkB,EAAE,4BAyChC,CAAA;AAED,eAAO,MAAM,sBAAsB,EAAE,yBA0BpC,CAAA"}

package/dist/collections/TierRequests/hooks/prepareTierRequest.js

@@ -0,0 +1,67 @@
+import { APIError } from 'payload';
+import { collectionOf } from '../../../collections/helpers';
+import { CTX_SYSTEM_REQUEST } from '../../../services/achievement/contextFlags';
+import { syncTierChangedLog } from '../../../services/achievement/recordEvent';
+import { relationId } from '../../../services/achievement/relationId';
+function scopeIdOf(data) {
+    return relationId(data?.scope);
+}
+/**
+ * System-created requests (reconcile / progression sync) may set user freely.
+ * Member creates are not used for tiers in v1 — reviewers/system own the flow.
+ */
+export const prepareTierRequest = async ({ data, operation, req, originalDoc, }) => {
+    if (!data)
+        return data;
+    if (operation === 'create') {
+        if (!req.context?.[CTX_SYSTEM_REQUEST]) {
+            const userId = req.user?.id;
+            if (typeof userId !== 'string')
+                throw new APIError('Unauthorized', 401);
+            data.user = userId;
+        }
+        const tierId = relationId(data.tier);
+        if (!tierId)
+            throw new APIError('tier required', 400);
+        const tier = await req.payload.findByID({
+            collection: collectionOf('tiers'),
+            id: tierId,
+            depth: 0,
+            overrideAccess: true,
+            req,
+        });
+        if (!tier)
+            throw new APIError(`Unknown tier: ${tierId}`, 400);
+        if (tier.requiresReview !== true) {
+            throw new APIError('This tier does not require review.', 400);
+        }
+        data.tier = tierId;
+        if (!data.status)
+            data.status = 'pending';
+        return data;
+    }
+    if (operation === 'update' && originalDoc) {
+        data.user = originalDoc.user;
+        data.tier = originalDoc.tier;
+    }
+    return data;
+};
+export const afterTierRequestChange = async ({ doc, operation, previousDoc, req, }) => {
+    const status = doc.status;
+    if (status !== 'approved')
+        return doc;
+    const previousStatus = operation === 'update' ? previousDoc?.status : undefined;
+    if (previousStatus === 'approved')
+        return doc;
+    const userId = relationId(doc.user);
+    if (!userId)
+        return doc;
+    const scopeId = scopeIdOf(doc);
+    await syncTierChangedLog({
+        payload: req.payload,
+        req: req,
+        userId,
+        scopeId,
+    });
+    return doc;
+};

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

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/collections/TierRequests/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAS,MAAM,SAAS,CAAA;AAOtD,wBAAgB,2BAA2B,IAAI,gBAAgB,CA2C9D"}

package/dist/collections/TierRequests/index.js

@@ -0,0 +1,47 @@
+import { collectionAdmin, collectionOf, optionalFields, slugOf } from '../helpers';
+import { scopeField, userField } from '../fields';
+import { access } from './access';
+import { hooks } from './hooks';
+export function buildTierRequestsCollection() {
+    return {
+        slug: slugOf('tierRequests'),
+        labels: {
+            singular: 'Tier Request',
+            plural: 'Tier Requests',
+        },
+        access: { ...access },
+        hooks,
+        admin: collectionAdmin({
+            useAsTitle: 'id',
+            defaultColumns: ['user', 'tier', 'status', 'createdAt'],
+            description: 'When a member has met a tier’s unlock rules but that tier requires review before it becomes their current tier.',
+        }),
+        fields: [
+            ...optionalFields(scopeField()),
+            userField(),
+            {
+                name: 'tier',
+                type: 'relationship',
+                relationTo: collectionOf('tiers'),
+                required: true,
+                index: true,
+            },
+            {
+                name: 'status',
+                type: 'select',
+                required: true,
+                defaultValue: 'pending',
+                options: [
+                    { label: 'Pending', value: 'pending' },
+                    { label: 'Approved', value: 'approved' },
+                    { label: 'Rejected', value: 'rejected' },
+                ],
+            },
+            {
+                name: 'note',
+                type: 'textarea',
+                admin: { description: 'Optional note from the reviewer.' },
+            },
+        ],
+    };
+}

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/collections/Tiers/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAA;AAQ/C,wBAAgB,oBAAoB,IAAI,gBAAgB,CA+EvD"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/collections/Tiers/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAA;AAQ/C,wBAAgB,oBAAoB,IAAI,gBAAgB,CAwFvD"}

package/dist/collections/Tiers/index.js

@@ -11,8 +11,8 @@ export function buildTiersCollection() {
         hooks,
         admin: collectionAdmin({
             useAsTitle: 'name',
-            defaultColumns: columnsWithOptionalScope(['name', 'slug', 'rank', 'scope']),
-            description: 'Unlock rules decide when someone reaches this step. Current tier is derived by walking the ladder (lowest rank first) — there is no stored progress row.',
+            defaultColumns: columnsWithOptionalScope(['name', 'slug', 'rank', 'requiresReview', 'scope']),
+            description: 'Unlock rules decide when someone reaches this step. Current tier is derived by walking the ladder (lowest rank first). Tiers with Requires review also need an approved tier request.',
         }),
         fields: [
             ...optionalFields(scopeField()),
@@ -67,12 +67,20 @@ export function buildTiersCollection() {
                         : []),
                 ],
             },
+            {
+                name: 'requiresReview',
+                type: 'checkbox',
+                defaultValue: false,
+                admin: {
+                    description: 'When enabled, unlock rules alone are not enough — an approved tier request is required before this step becomes the member’s current tier.',
+                },
+            },
             {
                 name: 'unlockRules',
                 type: 'group',
                 label: 'Unlock rules',
                 admin: {
-                    description: 'Rules that must pass to unlock this tier (all-of or any-of). Empty rules mean this step is open. The plugin derives current tier by walking ranks; optional tier.changed logs record moves.',
+                    description: 'Rules that must pass to unlock this tier (all-of or any-of). Empty rules mean this step is open. Current tier is derived by walking ranks; optional tier.changed logs record moves.',
                 },
                 fields: buildRuleTreeFields(),
             },

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

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

package/dist/collections/index.js

@@ -6,6 +6,7 @@ import { buildEventTypesCollection } from './EventTypes/index';
 import { buildGrantsCollection } from './Grants/index';
 import { buildLogsCollection } from './Logs/index';
 import { buildMetricsCollection } from './Metrics/index';
+import { buildTierRequestsCollection } from './TierRequests/index';
 import { buildTiersCollection } from './Tiers/index';
 const builders = {
     metrics: buildMetricsCollection,
@@ -14,6 +15,7 @@ const builders = {
     achievements: buildAchievementsCollection,
     grants: buildGrantsCollection,
     achievementRequests: buildAchievementRequestsCollection,
+    tierRequests: buildTierRequestsCollection,
     logs: buildLogsCollection,
 };
 /** Build achievement collections after plugin options are stored. */

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

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

package/dist/collections/slugs.js

@@ -14,6 +14,7 @@ export const DEFAULT_COLLECTION_BASE_SLUGS = {
     achievements: 'definitions',
     grants: 'grants',
     achievementRequests: 'requests',
+    tierRequests: 'tier-requests',
     logs: 'logs',
     eventTypes: 'event-types',
     metrics: 'metrics',