@dappermountain/payload-plugin-achievements 0.3.0 → 0.4.0

package/README.md

@@ -1,6 +1,6 @@
 # `@dappermountain/payload-plugin-achievements`
 
-A Payload CMS plugin for a **rule-based achievements and ranking system** — tiers, badges, points, grants, review workflows, and an append-only activity log — configured in Admin, not hard-coded in your app.
+A Payload CMS plugin for a **rule-based achievements and ranking system** — tiers, badges, points, grants, review workflows, and an append-only activity log — configured in Admin.
 
 Most gamification features end up as one-off collections and scattered hooks. This plugin gives you a reusable engine: define *what* can be earned and *how* it unlocks in Payload Admin, then record events from your application code. Current tier and progress are **derived** from rules and history, so you don’t maintain a separate progress table that drifts out of sync.
 
@@ -16,8 +16,9 @@ Most gamification features end up as one-off collections and scattered hooks. Th
 
 ## Requirements
 
-- Payload `^3.88`
-- `@payloadcms/ui` `^3.88`
+- Payload `^3.89`
+- `@payloadcms/ui` `^3.89`
+- `@payloadcms/richtext-lexical` `^3.89`
 - React `^19`
 
 ## Install
@@ -120,11 +121,15 @@ Unlock (tiers), eligibility, and completion (achievements) share the same rule t
 | `event-count` / `metric-minimum` | Fraction of the target |
 | `achievement-complete` | `1` if granted; otherwise rolls up that achievement’s completion (or eligibility) rules |
 
-**Computed elapsed metrics** — `kind: computed` + `compute: elapsed` + `unit` (`seconds` | `minutes` | `hours` | `days` | `years`) + `since` (built-in `user-created-at` / `first-event`, or a host `metricAnchors` key). Gate tenure with `metric-minimum` against that metric. Years use a fixed 365-day length (not calendar years). System seed only creates stored `points` — product computed metrics (e.g. `days`) are host-seeded after registering anchors.
+**Computed elapsed metrics** — `kind: computed` + `compute: elapsed` + `unit` (`seconds` | `minutes` | `hours` | `days` | `years`) + `since` (built-in `user-created-at` / `first-event`, or a host `metricAnchors` key). Gate tenure with `metric-minimum` against that metric. Years use a fixed 365-day length. System seed only creates stored `points` — product computed metrics (e.g. `days`) are host-seeded after registering anchors.
 
 **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`.
 
@@ -226,15 +231,59 @@ achievementPlugin({
 | --- | --- | --- |
 | `includeJoins` | `true` | Injects an `achievements` group on the users collection with joins to grants and requests. Set `false` if you own that UI yourself. |
 
+### `subjects`
+
+Host documents that logs may point at via a polymorphic `subject` field (same idea as `requiresActor` / `requiresMetric`).
+
+| Option | Default | Notes |
+| --- | --- | --- |
+| `collections` | `[]` | Allowlist of collection slugs (e.g. `posts`, `comments`). Empty / omit → subject feature is off (no log field, no event-type subject flags). |
+
+When configured:
+
+- Event types gain **Requires a subject** + optional **Subject collections** (`subjectRelationTo`).
+- Logs gain a polymorphic **Subject** relationship (Admin links to the host doc).
+- `recordLog({ subject: { relationTo, value } })` (or `logSubject(relationTo, value)`) writes the ref.
+- Prefer `subject` over stuffing ids into `data` JSON.
+
+```ts
+achievementPlugin({
+  canReview,
+  subjects: {
+    collections: ['posts', 'comments', 'endorsements'],
+  },
+})
+
+await seedAchievements(payload, {
+  eventTypes: [
+    {
+      name: 'Comment created',
+      slug: 'comment.created',
+      requiresSubject: true,
+      subjectRelationTo: ['comments'],
+    },
+  ],
+})
+
+await recordLog({
+  payload,
+  userId,
+  scopeId,
+  type: 'comment.created',
+  actorId: userId,
+  subject: logSubject('comments', commentId),
+})
+```
+
 ### `endpoints`
 
 | 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`
 
@@ -246,7 +295,7 @@ achievementPlugin({
   extensions: {
     metricAnchors: {
       'membership-granted': {
-        // Admin UI i18n (Payload label), not a CMS localized field
+        // Admin UI i18n (Payload label / OptionLabel)
         label: ({ t }) => t('custom:achievements:anchors:membershipGranted'),
         resolve: async ({ payload, userId, scopeId }) => {
           // return a Date from host data, or null
@@ -271,7 +320,7 @@ achievementPlugin({
 
 ## Server helpers
 
-Use these from hooks, jobs, and trusted endpoints — not from the public client:
+Use these from hooks, jobs, and trusted endpoints:
 
 ```ts
 import {
@@ -285,14 +334,34 @@ import {
   resolveCurrentTier,
   resolveTierProgress,
   getUserProgress,
+  loadUserProgressReviews,
+  buildUnlockRequirementLeaves,
   submitAchievementRequest,
   reviewAchievementRequest,
+  logSubject,
 } from '@dappermountain/payload-plugin-achievements'
 
 await recordLog({ payload, userId, scopeId, type: 'host.custom-kind', actorId })
+await recordLog({
+  payload,
+  userId,
+  scopeId,
+  type: 'comment.created',
+  actorId: userId,
+  subject: logSubject('comments', commentId),
+})
 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 })
@@ -326,6 +395,8 @@ Engine log `data` for those system events uses a shared transition envelope:
 | `achievement.granted` | `null` | achievement |
 | `achievement.revoked` | achievement | `null` |
 
+Host document links belong on polymorphic **`subject`** (when `subjects.collections` is set), not inside `data`.
+
 Turning **Requires review** off on a definition or tier **approves pending requests** for that row only (each waiting user goes through the existing request hooks).
 
 **Admin:** Grants list includes **Repair progression**, which `POST`s the reconcile endpoint (requires `canReview`).
@@ -334,7 +405,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>` |
@@ -357,7 +428,15 @@ import {
 await seedAchievementCatalog(payload) // system metrics + event types (English)
 
 await seedAchievements(payload, {
-  eventTypes: [{ name: 'Custom kind', slug: 'host.custom-kind', requiresActor: true }],
+  eventTypes: [
+    { name: 'Custom kind', slug: 'host.custom-kind', requiresActor: true },
+    {
+      name: 'Comment created',
+      slug: 'comment.created',
+      requiresSubject: true,
+      subjectRelationTo: ['comments'],
+    },
+  ],
   metrics: [{ name: 'Streak days', slug: 'streak-days' }],
   tiers: [
     {

package/dist/admin/SubjectField.d.ts

@@ -0,0 +1,14 @@
+import type { RelationshipFieldClientProps } from 'payload';
+import React from 'react';
+type SubjectFieldProps = RelationshipFieldClientProps & {
+    eventTypesSlug: string;
+    /** Plugin allowlist — used when the event type leaves `subjectRelationTo` empty. */
+    subjectCollections: string[];
+};
+/**
+ * Polymorphic subject — only when the selected event type requires a host document.
+ * Clears the value when the type does not require a subject.
+ */
+export declare function SubjectField(props: SubjectFieldProps): React.JSX.Element | null;
+export {};
+//# sourceMappingURL=SubjectField.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"SubjectField.d.ts","sourceRoot":"","sources":["../../src/admin/SubjectField.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,SAAS,CAAA;AAE3D,OAAO,KAA6B,MAAM,OAAO,CAAA;AAIjD,KAAK,iBAAiB,GAAG,4BAA4B,GAAG;IACtD,cAAc,EAAE,MAAM,CAAA;IACtB,oFAAoF;IACpF,kBAAkB,EAAE,MAAM,EAAE,CAAA;CAC7B,CAAA;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,iBAAiB,4BAoCpD"}

package/dist/admin/SubjectField.js

@@ -0,0 +1,38 @@
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+import { RelationshipField, useField } from '@payloadcms/ui';
+import { useEffect, useMemo } from 'react';
+import { useEventTypeFlags } from './useEventTypeFlags.js';
+/**
+ * Polymorphic subject — only when the selected event type requires a host document.
+ * Clears the value when the type does not require a subject.
+ */
+export function SubjectField(props) {
+    const { eventTypesSlug, subjectCollections, ...fieldArgs } = props;
+    const { requiresSubject, subjectRelationTo } = useEventTypeFlags(eventTypesSlug);
+    const { setValue, value } = useField({ path: fieldArgs.path });
+    const allowedCollections = useMemo(() => {
+        if (subjectRelationTo.length > 0) {
+            return subjectRelationTo.filter((slug) => subjectCollections.includes(slug));
+        }
+        return subjectCollections;
+    }, [subjectCollections, subjectRelationTo]);
+    useEffect(() => {
+        if (!requiresSubject && value != null && value !== '') {
+            setValue(null);
+            return;
+        }
+        if (!requiresSubject || !value || typeof value !== 'object')
+            return;
+        const relationTo = value.relationTo;
+        if (typeof relationTo === 'string' && allowedCollections.length > 0 && !allowedCollections.includes(relationTo)) {
+            setValue(null);
+        }
+    }, [requiresSubject, setValue, value, allowedCollections]);
+    if (!requiresSubject || allowedCollections.length === 0)
+        return null;
+    return (_jsx(RelationshipField, { ...fieldArgs, field: {
+            ...fieldArgs.field,
+            relationTo: allowedCollections,
+        } }));
+}

package/dist/admin/useEventTypeFlags.d.ts

@@ -1,6 +1,8 @@
 export type EventTypeFlags = {
     requiresActor: boolean;
     requiresMetric: boolean;
+    requiresSubject: boolean;
+    subjectRelationTo: string[];
 };
 /** Resolve event-type flags for the selected `type` field (fetch when only an id is present). */
 export declare function useEventTypeFlags(eventTypesSlug: string): EventTypeFlags;

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

@@ -1 +1 @@
-{"version":3,"file":"useEventTypeFlags.d.ts","sourceRoot":"","sources":["../../src/admin/useEventTypeFlags.ts"],"names":[],"mappings":"AAKA,MAAM,MAAM,cAAc,GAAG;IAC3B,aAAa,EAAE,OAAO,CAAA;IACtB,cAAc,EAAE,OAAO,CAAA;CACxB,CAAA;AA2BD,iGAAiG;AACjG,wBAAgB,iBAAiB,CAAC,cAAc,EAAE,MAAM,GAAG,cAAc,CAyCxE"}
+{"version":3,"file":"useEventTypeFlags.d.ts","sourceRoot":"","sources":["../../src/admin/useEventTypeFlags.ts"],"names":[],"mappings":"AAKA,MAAM,MAAM,cAAc,GAAG;IAC3B,aAAa,EAAE,OAAO,CAAA;IACtB,cAAc,EAAE,OAAO,CAAA;IACvB,eAAe,EAAE,OAAO,CAAA;IACxB,iBAAiB,EAAE,MAAM,EAAE,CAAA;CAC5B,CAAA;AAqDD,iGAAiG;AACjG,wBAAgB,iBAAiB,CAAC,cAAc,EAAE,MAAM,GAAG,cAAc,CA4CxE"}

package/dist/admin/useEventTypeFlags.js

@@ -15,19 +15,35 @@ function relationId(value) {
     }
     return null;
 }
+function readSubjectRelationTo(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.filter((entry) => typeof entry === 'string' && entry.trim().length > 0);
+}
 function flagsFromValue(typeValue) {
     if (!typeValue || typeof typeValue !== 'object')
         return null;
-    if (!('requiresActor' in typeValue || 'requiresMetric' in typeValue || 'slug' in typeValue)) {
+    if (!('requiresActor' in typeValue ||
+        'requiresMetric' in typeValue ||
+        'requiresSubject' in typeValue ||
+        'subjectRelationTo' in typeValue ||
+        'slug' in typeValue)) {
         return null;
     }
     const row = typeValue;
     return {
         requiresActor: Boolean(row.requiresActor),
         requiresMetric: Boolean(row.requiresMetric) || row.slug === 'metric.delta',
+        requiresSubject: Boolean(row.requiresSubject),
+        subjectRelationTo: readSubjectRelationTo(row.subjectRelationTo),
     };
 }
-const empty = { requiresActor: false, requiresMetric: false };
+const empty = {
+    requiresActor: false,
+    requiresMetric: false,
+    requiresSubject: false,
+    subjectRelationTo: [],
+};
 /** Resolve event-type flags for the selected `type` field (fetch when only an id is present). */
 export function useEventTypeFlags(eventTypesSlug) {
     const { config } = useConfig();
@@ -47,7 +63,9 @@ export function useEventTypeFlags(eventTypesSlug) {
         const controller = new AbortController();
         const api = config.routes?.api ?? '/api';
         const serverURL = config.serverURL ?? '';
-        const url = `${serverURL}${api}/${eventTypesSlug}/${typeId}?depth=0&select[requiresActor]=true&select[requiresMetric]=true&select[slug]=true`;
+        const url = `${serverURL}${api}/${eventTypesSlug}/${typeId}` +
+            `?depth=0&select[requiresActor]=true&select[requiresMetric]=true` +
+            `&select[requiresSubject]=true&select[subjectRelationTo]=true&select[slug]=true`;
         void fetch(url, { credentials: 'include', signal: controller.signal })
             .then(async (res) => {
             if (!res.ok) {

package/dist/cli/reconcile.d.ts

@@ -12,7 +12,7 @@ export declare function runReconcileCli(args: {
     config: SanitizedConfig | Promise<SanitizedConfig>;
     argv?: string[];
     filters?: ReconcileCliFilters;
-    /** When false, return the result instead of exiting the process. Default true. */
+    /** When false, return the result and leave the process running. Default true. */
     exit?: boolean;
 }): Promise<ReconcileProgressionResult>;
 //# sourceMappingURL=reconcile.d.ts.map

package/dist/cli/reconcile.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"reconcile.d.ts","sourceRoot":"","sources":["../../src/cli/reconcile.ts"],"names":[],"mappings":"AAAA,OAAO,EAAc,KAAK,eAAe,EAAE,MAAM,SAAS,CAAA;AAE1D,OAAO,EAEL,KAAK,wBAAwB,EAC7B,KAAK,0BAA0B,EAChC,MAAM,sCAAsC,CAAA;AAE7C,MAAM,MAAM,mBAAmB,GAAG,IAAI,CAAC,wBAAwB,EAAE,SAAS,GAAG,KAAK,CAAC,CAAA;AA2BnF,sFAAsF;AACtF,wBAAgB,qBAAqB,CAAC,IAAI,GAAE,MAAM,EAA0B,GAAG,mBAAmB,CAUjG;AAED,wBAAgB,qBAAqB,IAAI,IAAI,CAc5C;AAED;;;GAGG;AACH,wBAAsB,eAAe,CAAC,IAAI,EAAE;IAC1C,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC,CAAA;IAClD,IAAI,CAAC,EAAE,MAAM,EAAE,CAAA;IACf,OAAO,CAAC,EAAE,mBAAmB,CAAA;IAC7B,kFAAkF;IAClF,IAAI,CAAC,EAAE,OAAO,CAAA;CACf,GAAG,OAAO,CAAC,0BAA0B,CAAC,CA4BtC"}
+{"version":3,"file":"reconcile.d.ts","sourceRoot":"","sources":["../../src/cli/reconcile.ts"],"names":[],"mappings":"AAAA,OAAO,EAAc,KAAK,eAAe,EAAE,MAAM,SAAS,CAAA;AAE1D,OAAO,EAEL,KAAK,wBAAwB,EAC7B,KAAK,0BAA0B,EAChC,MAAM,sCAAsC,CAAA;AAE7C,MAAM,MAAM,mBAAmB,GAAG,IAAI,CAAC,wBAAwB,EAAE,SAAS,GAAG,KAAK,CAAC,CAAA;AA2BnF,sFAAsF;AACtF,wBAAgB,qBAAqB,CAAC,IAAI,GAAE,MAAM,EAA0B,GAAG,mBAAmB,CAUjG;AAED,wBAAgB,qBAAqB,IAAI,IAAI,CAc5C;AAED;;;GAGG;AACH,wBAAsB,eAAe,CAAC,IAAI,EAAE;IAC1C,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC,CAAA;IAClD,IAAI,CAAC,EAAE,MAAM,EAAE,CAAA;IACf,OAAO,CAAC,EAAE,mBAAmB,CAAA;IAC7B,iFAAiF;IACjF,IAAI,CAAC,EAAE,OAAO,CAAA;CACf,GAAG,OAAO,CAAC,0BAA0B,CAAC,CA4BtC"}

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/collections/EventTypes/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAS,MAAM,SAAS,CAAA;AAOtD,wBAAgB,yBAAyB,IAAI,gBAAgB,CAgE5D"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/collections/EventTypes/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAS,MAAM,SAAS,CAAA;AAqCtD,wBAAgB,yBAAyB,IAAI,gBAAgB,CAoE5D"}

package/dist/collections/EventTypes/index.js

@@ -1,8 +1,36 @@
+import { getAchievementOptions } from '../../options-store.js';
 import { collectionAdmin, collectionOf, columnsWithOptionalScope, optionalFields, slugOf } from '../helpers.js';
 import { localizedNameField, scopeField } from '../fields/index.js';
 import { access } from './access/index.js';
 import { hooks } from './hooks/index.js';
+function subjectCatalogFields() {
+    const collections = getAchievementOptions().subjectCollections;
+    if (collections.length === 0)
+        return [];
+    return [
+        {
+            name: 'requiresSubject',
+            type: 'checkbox',
+            defaultValue: false,
+            label: 'Requires a subject',
+            admin: {
+                description: 'Turn this on when the log points at a host document (for example a post or comment). We’ll ask for that document when it’s logged.',
+            },
+        },
+        {
+            name: 'subjectRelationTo',
+            type: 'select',
+            hasMany: true,
+            options: collections.map((slug) => ({ label: slug, value: slug })),
+            admin: {
+                condition: (_, siblingData) => Boolean(siblingData?.requiresSubject),
+                description: 'Which host collections this type may reference. Leave empty to allow any collection from the plugin subjects allowlist.',
+            },
+        },
+    ];
+}
 export function buildEventTypesCollection() {
+    const subjectFields = subjectCatalogFields();
     return {
         slug: slugOf('eventTypes'),
         access: { ...access },
@@ -14,6 +42,7 @@ export function buildEventTypesCollection() {
                 'slug',
                 'requiresActor',
                 'requiresMetric',
+                ...(subjectFields.length > 0 ? ['requiresSubject'] : []),
                 'system',
                 'scope',
             ]),
@@ -46,6 +75,7 @@ export function buildEventTypesCollection() {
                     description: 'Turn this on when the entry changes a score (like points). We’ll ask which metric and by how much.',
                 },
             },
+            ...subjectFields,
             {
                 name: 'system',
                 type: 'checkbox',

package/dist/collections/Logs/fields/validators.d.ts

@@ -2,4 +2,5 @@ import type { Validate } from 'payload';
 export declare const validateActor: Validate;
 export declare const validateMetric: Validate;
 export declare const validateChange: Validate;
+export declare const validateSubject: Validate;
 //# sourceMappingURL=validators.d.ts.map

package/dist/collections/Logs/fields/validators.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validators.d.ts","sourceRoot":"","sources":["../../../../src/collections/Logs/fields/validators.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAA;AASvC,eAAO,MAAM,aAAa,EAAE,QAW3B,CAAA;AAED,eAAO,MAAM,cAAc,EAAE,QA0B5B,CAAA;AAED,eAAO,MAAM,cAAc,EAAE,QAW5B,CAAA"}
+{"version":3,"file":"validators.d.ts","sourceRoot":"","sources":["../../../../src/collections/Logs/fields/validators.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAA;AAavC,eAAO,MAAM,aAAa,EAAE,QAW3B,CAAA;AAED,eAAO,MAAM,cAAc,EAAE,QA0B5B,CAAA;AAED,eAAO,MAAM,cAAc,EAAE,QAW5B,CAAA;AAED,eAAO,MAAM,eAAe,EAAE,QAqC7B,CAAA"}

package/dist/collections/Logs/fields/validators.js

@@ -1,5 +1,7 @@
+import { getAchievementOptions } from '../../../options-store.js';
 import { collectionOf } from '../../../collections/helpers.js';
-import { eventTypeRequiresActor, eventTypeRequiresMetric, } from '../../../services/achievement/eventTypeRequiresActor.js';
+import { eventTypeRequiresActor, eventTypeRequiresMetric, eventTypeSubjectRelationTo, getEventTypeFlags, } from '../../../services/achievement/eventTypeRequiresActor.js';
+import { readLogSubject } from '../../../services/achievement/logSubject.js';
 import { relationId } from '../../../services/achievement/relationId.js';
 export const validateActor = async (value, { data, req }) => {
     if (!req?.payload)
@@ -55,3 +57,37 @@ export const validateChange = async (value, { data, req }) => {
     }
     return true;
 };
+export const validateSubject = async (value, { data, req }) => {
+    if (!req?.payload)
+        return true;
+    const allowlist = getAchievementOptions().subjectCollections;
+    if (allowlist.length === 0)
+        return true;
+    const typeId = relationId(data?.type);
+    if (!typeId)
+        return true;
+    const flags = await getEventTypeFlags({
+        payload: req.payload,
+        req,
+        typeIdOrDoc: typeId,
+    });
+    const subject = readLogSubject(value);
+    if (!flags.requiresSubject) {
+        return true;
+    }
+    if (!subject) {
+        return 'This log type needs a subject (the host document it is about).';
+    }
+    if (!allowlist.includes(subject.relationTo)) {
+        return `Subject collection "${subject.relationTo}" is not in the plugin subjects allowlist.`;
+    }
+    const allowed = await eventTypeSubjectRelationTo({
+        payload: req.payload,
+        req,
+        typeIdOrDoc: typeId,
+    });
+    if (allowed.length > 0 && !allowed.includes(subject.relationTo)) {
+        return `This log type only allows subjects from: ${allowed.join(', ')}.`;
+    }
+    return true;
+};

package/dist/collections/Logs/hooks/ensureTypeRequirements.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ensureTypeRequirements.d.ts","sourceRoot":"","sources":["../../../../src/collections/Logs/hooks/ensureTypeRequirements.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,SAAS,CAAA;AAU3D,eAAO,MAAM,sBAAsB,EAAE,4BAmDpC,CAAA"}
+{"version":3,"file":"ensureTypeRequirements.d.ts","sourceRoot":"","sources":["../../../../src/collections/Logs/hooks/ensureTypeRequirements.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,SAAS,CAAA;AAc3D,eAAO,MAAM,sBAAsB,EAAE,4BA+DpC,CAAA"}

package/dist/collections/Logs/hooks/ensureTypeRequirements.js

@@ -1,6 +1,8 @@
 import { APIError } from 'payload';
+import { getAchievementOptions } from '../../../options-store.js';
 import { collectionOf } from '../../../collections/helpers.js';
-import { eventTypeRequiresActor, eventTypeRequiresMetric, } from '../../../services/achievement/eventTypeRequiresActor.js';
+import { eventTypeSubjectRelationTo, getEventTypeFlags, } from '../../../services/achievement/eventTypeRequiresActor.js';
+import { readLogSubject } from '../../../services/achievement/logSubject.js';
 import { relationId } from '../../../services/achievement/relationId.js';
 export const ensureTypeRequirements = async ({ data, req }) => {
     if (!data)
@@ -8,18 +10,11 @@ export const ensureTypeRequirements = async ({ data, req }) => {
     const typeId = relationId(data.type);
     if (!typeId)
         return data;
-    const flags = {
-        requiresActor: await eventTypeRequiresActor({
-            payload: req.payload,
-            req,
-            typeIdOrDoc: typeId,
-        }),
-        requiresMetric: await eventTypeRequiresMetric({
-            payload: req.payload,
-            req,
-            typeIdOrDoc: typeId,
-        }),
-    };
+    const flags = await getEventTypeFlags({
+        payload: req.payload,
+        req,
+        typeIdOrDoc: typeId,
+    });
     if (flags.requiresActor && !relationId(data.actor)) {
         throw new APIError('This log type needs an actor (who caused it).', 400);
     }
@@ -44,5 +39,19 @@ export const ensureTypeRequirements = async ({ data, req }) => {
             throw new APIError('Computed metrics cannot be changed with a metric delta. Use a stored metric such as Points.', 400);
         }
     }
+    if (flags.requiresSubject && getAchievementOptions().subjectCollections.length > 0) {
+        const subject = readLogSubject(data.subject);
+        if (!subject) {
+            throw new APIError('This log type needs a subject (the host document it is about).', 400);
+        }
+        const allowed = await eventTypeSubjectRelationTo({
+            payload: req.payload,
+            req,
+            typeIdOrDoc: typeId,
+        });
+        if (allowed.length > 0 && !allowed.includes(subject.relationTo)) {
+            throw new APIError(`This log type only allows subjects from: ${allowed.join(', ')}.`, 400);
+        }
+    }
     return data;
 };

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/collections/Logs/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAS,MAAM,SAAS,CAAA;AAUtD,+EAA+E;AAC/E,wBAAgB,mBAAmB,IAAI,gBAAgB,CA6GtD"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/collections/Logs/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAS,MAAM,SAAS,CAAA;AAqCtD,+EAA+E;AAC/E,wBAAgB,mBAAmB,IAAI,gBAAgB,CAuHtD"}

package/dist/collections/Logs/index.js

@@ -3,12 +3,34 @@ import { collectionAdmin, collectionOf, optionalFields, slugOf } from '../helper
 import { getAchievementOptions } from '../../options-store.js';
 import { scopeField, userField } from '../fields/index.js';
 import { access } from './access/index.js';
-import { validateActor, validateChange, validateMetric } from './fields/validators.js';
+import { validateActor, validateChange, validateMetric, validateSubject, } from './fields/validators.js';
 import { hooks } from './hooks/index.js';
+function subjectLogField(eventTypesSlug) {
+    const collections = getAchievementOptions().subjectCollections;
+    if (collections.length === 0)
+        return null;
+    return {
+        name: 'subject',
+        type: 'relationship',
+        relationTo: collections,
+        index: true,
+        validate: validateSubject,
+        admin: {
+            description: 'Host document this entry is about (post, comment, …).',
+            components: {
+                Field: {
+                    path: '@dappermountain/payload-plugin-achievements/client#SubjectField',
+                    clientProps: { eventTypesSlug, subjectCollections: collections },
+                },
+            },
+        },
+    };
+}
 /** Append-only occurrence log. `type` / `metric` are catalog relationships. */
 export function buildLogsCollection() {
     const users = getAchievementOptions().usersCollectionSlug ?? 'users';
     const eventTypesSlug = collectionOf('eventTypes');
+    const subjectField = subjectLogField(eventTypesSlug);
     return {
         slug: slugOf('logs'),
         labels: {
@@ -19,7 +41,15 @@ export function buildLogsCollection() {
         hooks,
         admin: collectionAdmin({
             useAsTitle: 'id',
-            defaultColumns: ['type', 'user', 'actor', 'metric', 'change', 'createdAt'],
+            defaultColumns: [
+                'type',
+                'user',
+                'actor',
+                ...(subjectField ? ['subject'] : []),
+                'metric',
+                'change',
+                'createdAt',
+            ],
             description: 'Member activity history — grants, revokes, score changes, tier moves, and host custom events. Not a second grant store.',
         }),
         fields: [
@@ -88,6 +118,7 @@ export function buildLogsCollection() {
                     },
                 ],
             },
+            ...(subjectField ? [subjectField] : []),
             {
                 type: 'collapsible',
                 label: 'Details',
@@ -105,7 +136,7 @@ export function buildLogsCollection() {
                         name: 'data',
                         type: 'json',
                         admin: {
-                            description: 'Engine transition envelope: `{ from, to }` each `{ id, slug? }` or null (tier.changed, achievement.granted/revoked). Hosts may add extra keys.',
+                            description: 'Engine transition envelope: `{ from, to }` each `{ id, slug? }` or null (tier.changed, achievement.granted/revoked). Prefer `subject` for host document links.',
                         },
                     },
                 ],

package/dist/defaults.d.ts

@@ -4,13 +4,15 @@ export declare const DEFAULT_USERS_COLLECTION = "users";
 export declare const DEFAULT_ME_ENDPOINT_PATH = "/achievements/me";
 export declare const DEFAULT_LEADERBOARD_ENDPOINT_PATH = "/achievements/leaderboard";
 export declare const DEFAULT_RECONCILE_ENDPOINT_PATH = "/achievements/reconcile";
-export type ResolvedAchievementOptions = Omit<AchievementPluginOptions, 'users' | 'endpoints'> & {
+export type ResolvedAchievementOptions = Omit<AchievementPluginOptions, 'users' | 'endpoints' | 'subjects'> & {
     enabled: boolean;
     seedSystemCatalog: boolean;
     usersCollectionSlug: string;
     users: {
         includeJoins: boolean;
     };
+    /** Host collections allowed as polymorphic log subjects (empty = feature off). */
+    subjectCollections: string[];
     /** Resolved collection slug map (after prefix + overrides). */
     collectionSlugs: ReturnType<typeof resolveCollectionSlugs>;
     /** Admin nav group for plugin collections (`false` = ungrouped). */
@@ -21,6 +23,8 @@ export type ResolvedAchievementOptions = Omit<AchievementPluginOptions, 'users'
         reconcile: string | false;
     };
 };
+/** Unique, non-empty collection slugs from plugin `subjects.collections`. */
+export declare function resolveSubjectCollections(options?: AchievementPluginOptions): string[];
 export declare function resolveMeEndpointPath(me?: string | false): string | false;
 export declare function resolveLeaderboardEndpointPath(path?: string | false): string | false;
 export declare function resolveReconcileEndpointPath(path?: string | false): string | false;

package/dist/defaults.d.ts.map

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