@dappermountain/payload-plugin-achievements 0.3.0 → 0.4.0

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,13 +2,20 @@ 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';
 export { resolveMetricValue, loadMetricDoc } from './resolveMetricValue.js';
 export { resolveElapsedAnchor } from './resolveElapsedAnchor.js';
 export { recordEvent, recordLog, recordMetricChange, syncTierChangedLog } from './recordEvent.js';
+export { logSubject, readLogSubject } from './logSubject.js';
+export type { LogSubjectRef } from './logSubject.js';
 export { resolveCurrentTier } from './resolveCurrentTier.js';
 export type { ResolvedTier } from './resolveCurrentTier.js';
 export { resolveTierProgress } from './resolveTierProgress.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,UAAU,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAC5D,YAAY,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAA;AACpD,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,11 +1,14 @@
 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';
 export { resolveElapsedAnchor } from './resolveElapsedAnchor.js';
 export { recordEvent, recordLog, recordMetricChange, syncTierChangedLog } from './recordEvent.js';
+export { logSubject, readLogSubject } from './logSubject.js';
 export { resolveCurrentTier } from './resolveCurrentTier.js';
 export { resolveTierProgress } from './resolveTierProgress.js';
 export { grantAchievement, submitAchievementRequest } from './submitAchievementRequest.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/dist/services/achievement/logSubject.d.ts

@@ -0,0 +1,13 @@
+/** Polymorphic relationship value (Payload `relationTo` + `value`). */
+export type LogSubjectRef = {
+    relationTo: string;
+    value: string;
+};
+/** Build a log subject ref for `recordLog({ subject })`. */
+export declare function logSubject(relationTo: string, value: string): LogSubjectRef;
+/**
+ * Normalize a polymorphic relationship (Admin / Local API shape) to `{ relationTo, value }`.
+ * Accepts nested docs (`value: { id }`) and plain ids under `value`.
+ */
+export declare function readLogSubject(value: unknown): LogSubjectRef | null;
+//# sourceMappingURL=logSubject.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"logSubject.d.ts","sourceRoot":"","sources":["../../../src/services/achievement/logSubject.ts"],"names":[],"mappings":"AAEA,uEAAuE;AACvE,MAAM,MAAM,aAAa,GAAG;IAC1B,UAAU,EAAE,MAAM,CAAA;IAClB,KAAK,EAAE,MAAM,CAAA;CACd,CAAA;AAED,4DAA4D;AAC5D,wBAAgB,UAAU,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,aAAa,CAE3E;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,aAAa,GAAG,IAAI,CAOnE"}

package/dist/services/achievement/logSubject.js

@@ -0,0 +1,20 @@
+import { relationId } from './relationId.js';
+/** Build a log subject ref for `recordLog({ subject })`. */
+export function logSubject(relationTo, value) {
+    return { relationTo, value };
+}
+/**
+ * Normalize a polymorphic relationship (Admin / Local API shape) to `{ relationTo, value }`.
+ * Accepts nested docs (`value: { id }`) and plain ids under `value`.
+ */
+export function readLogSubject(value) {
+    if (!value || typeof value !== 'object')
+        return null;
+    const row = value;
+    if (typeof row.relationTo !== 'string' || !row.relationTo.trim())
+        return null;
+    const id = relationId(row.value);
+    if (!id)
+        return null;
+    return { relationTo: row.relationTo.trim(), value: id };
+}

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

@@ -1,4 +1,5 @@
 import type { Payload, PayloadRequest } from 'payload';
+import { type LogSubjectRef } from './logSubject.js';
 export type RecordLogInput = {
     payload: Payload;
     req?: PayloadRequest;
@@ -12,6 +13,11 @@ export type RecordLogInput = {
     /** Signed amount the metric moved (for metric.delta logs). */
     change?: number;
     reason?: string;
+    /**
+     * Host document this entry is about (polymorphic).
+     * Preferred over stuffing ids into `data` when the host configured `subjects.collections`.
+     */
+    subject?: LogSubjectRef | null;
     data?: Record<string, unknown> | null;
 };
 /** Append a catalogued occurrence to the achievement log. */

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

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

package/dist/services/achievement/recordEvent.js

@@ -1,7 +1,9 @@
 import { APIError } from 'payload';
 import { DEFAULT_ACHIEVEMENT_METRIC_SLUG } from '../../catalog.js';
 import { collectionOf } from '../../collections/helpers.js';
-import { eventTypeRequiresActor } from './eventTypeRequiresActor.js';
+import { getAchievementOptions } from '../../options-store.js';
+import { eventTypeSubjectRelationTo, getEventTypeFlags, } from './eventTypeRequiresActor.js';
+import { readLogSubject } from './logSubject.js';
 import { applyMetricBalanceDelta } from './metricBalances.js';
 import { transitionLogData, transitionToId } from './logData.js';
 import { loadMetricDoc } from './resolveMetricValue.js';
@@ -33,9 +35,34 @@ export async function recordLog(args) {
             value: args.metric,
         })
         : undefined;
-    if (await eventTypeRequiresActor({ payload: args.payload, req: args.req, typeIdOrDoc: typeId })) {
-        if (!args.actorId) {
-            throw new APIError('This log type needs an actor (who caused it).', 400);
+    const flags = await getEventTypeFlags({
+        payload: args.payload,
+        req: args.req,
+        typeIdOrDoc: typeId,
+    });
+    if (flags.requiresActor && !args.actorId) {
+        throw new APIError('This log type needs an actor (who caused it).', 400);
+    }
+    const allowlist = getAchievementOptions().subjectCollections;
+    let subject;
+    if (args.subject) {
+        const parsed = readLogSubject(args.subject) ?? args.subject;
+        subject = parsed;
+    }
+    if (flags.requiresSubject && allowlist.length > 0) {
+        if (!subject) {
+            throw new APIError('This log type needs a subject (the host document it is about).', 400);
+        }
+        if (!allowlist.includes(subject.relationTo)) {
+            throw new APIError(`Subject collection "${subject.relationTo}" is not in the plugin subjects allowlist.`, 400);
+        }
+        const allowed = await eventTypeSubjectRelationTo({
+            payload: args.payload,
+            req: args.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 args.payload.create({
@@ -48,6 +75,7 @@ export async function recordLog(args) {
             metric: metricId,
             change: args.change,
             reason: args.reason,
+            ...(subject ? { subject } : {}),
             data: args.data ?? undefined,
         },
         overrideAccess: true,

package/dist/types.d.ts

@@ -9,7 +9,7 @@ export type AchievementMetricAnchor = (args: {
 /**
  * Anchor with an Admin label.
  * `label` is a Payload Admin UI string ({@link OptionLabel}): plain string, `{ en, es, … }`,
- * or `({ t }) => t('custom:…')` — not CMS `localization`.
+ * or `({ t }) => t('custom:…')` (Admin UI / OptionLabel).
  */
 export type AchievementMetricAnchorConfig = {
     label: OptionLabel;
@@ -40,11 +40,11 @@ export type AchievementRuleType = {
     /**
      * Optional fractional progress toward this leaf (0..1).
      * When omitted, progress falls back to `evaluate` → 0 or 1.
-     * Used for next-tier ladder fill and host UIs — not for unlock boolean.
+     * Used for next-tier ladder fill and host UIs (progress display).
      */
     progress?: (args: AchievementRuleEvalArgs) => Promise<number> | number;
     /**
-     * `gate` rules (e.g. `tier-at-least`) are prerequisites, not progress.
+     * `gate` rules (e.g. `tier-at-least`) are prerequisites that must already hold.
      * They are omitted from AND averages. Default: `requirement`.
      */
     progressRole?: 'requirement' | 'gate';
@@ -110,6 +110,17 @@ export type AchievementEndpointsOptions = {
      */
     reconcile?: string | false;
 };
+/**
+ * Host documents that achievement logs may point at (polymorphic `subject`).
+ * Empty / omitted → subject field is not registered (engine stays host-agnostic).
+ */
+export type AchievementSubjectsOptions = {
+    /**
+     * Collection slugs allowed on log `subject.relationTo` (e.g. `posts`, `comments`).
+     * Event types pick a subset via `subjectRelationTo`; validation rejects anything outside this list.
+     */
+    collections?: string[];
+};
 export type AchievementPluginOptions = {
     /**
      * Whether the user may review requests and manage achievement catalogs for a scope.
@@ -121,6 +132,11 @@ export type AchievementPluginOptions = {
     enabled?: boolean;
     /** Custom root API routes registered by the plugin. */
     endpoints?: AchievementEndpointsOptions;
+    /**
+     * Polymorphic log subjects — host allowlist of collections.
+     * When set, event types gain `requiresSubject` / `subjectRelationTo` and logs gain `subject`.
+     */
+    subjects?: AchievementSubjectsOptions;
     extensions?: {
         /** Custom rule evaluators merged with built-ins. */
         ruleTypes?: AchievementRuleType[];

package/dist/types.d.ts.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dappermountain/payload-plugin-achievements",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "A robust, Admin-configured achievements engine for Payload: composable unlock rules, derived rank progress, request/review grants, metrics, and scoped multi-tenant support.",
   "license": "MIT",
   "type": "module",
@@ -69,21 +69,21 @@
     "skills:check": "bunx skills check -p"
   },
   "peerDependencies": {
-    "@payloadcms/richtext-lexical": "^3.88.0",
-    "@payloadcms/ui": "^3.88.0",
+    "@payloadcms/richtext-lexical": "^3.89.0",
+    "@payloadcms/ui": "^3.89.0",
     "lucide-react": "^0.543.0",
-    "payload": "^3.88.0",
+    "payload": "^3.89.0",
     "react": "^19.0.0"
   },
   "devDependencies": {
     "@dappermountain/agent-payload": "^0.1.5",
     "@dappermountain/agent-practices": "^0.1.2",
-    "@payloadcms/richtext-lexical": "3.88.0",
-    "@payloadcms/ui": "3.88.0",
+    "@payloadcms/richtext-lexical": "3.89.0",
+    "@payloadcms/ui": "3.89.0",
     "@types/bun": "1.4.0",
     "@types/react": "^19.0.0",
     "lucide-react": "0.543.0",
-    "payload": "3.88.0",
+    "payload": "3.89.0",
     "prettier": "^3.6.2",
     "react": "19.2.4",
     "typescript": "5.9.2"