@dappermountain/payload-plugin-achievements 0.1.0

package/dist/services/achievement/getUserProgress.js

@@ -0,0 +1,163 @@
+import { collectionOf } from '../../collections/helpers';
+import { relationId } from './relationId';
+import { resolveCurrentTier } from './resolveCurrentTier';
+import { userScopeWhere } from './where';
+function leanCatalog(value) {
+    const id = relationId(value);
+    if (!id)
+        return null;
+    if (!value || typeof value !== 'object')
+        return { id };
+    const row = value;
+    return {
+        id,
+        ...(typeof row.name === 'string' && row.name ? { name: row.name } : {}),
+        ...(typeof row.slug === 'string' && row.slug ? { slug: row.slug } : {}),
+        ...(typeof row.description === 'string' && row.description
+            ? { description: row.description }
+            : {}),
+    };
+}
+function leanGrant(doc) {
+    return {
+        id: doc.id,
+        achievement: leanCatalog(doc.achievement),
+        completedAt: doc.completedAt ?? null,
+        note: doc.note ?? null,
+        scopeId: relationId(doc.scope) ?? null,
+        updatedAt: doc.updatedAt ?? null,
+        createdAt: doc.createdAt ?? null,
+    };
+}
+function leanRequest(doc) {
+    return {
+        id: doc.id,
+        status: doc.status ?? null,
+        achievement: leanCatalog(doc.achievement),
+        reason: doc.reason ?? null,
+        updatedAt: doc.updatedAt ?? null,
+        createdAt: doc.createdAt ?? null,
+    };
+}
+function mapPaginatedDocs(result, mapDoc) {
+    return {
+        docs: result.docs.map(mapDoc),
+        hasNextPage: result.hasNextPage,
+        hasPrevPage: result.hasPrevPage,
+        limit: result.limit,
+        nextPage: result.nextPage,
+        page: result.page,
+        pagingCounter: result.pagingCounter,
+        prevPage: result.prevPage,
+        totalDocs: result.totalDocs,
+        totalPages: result.totalPages,
+    };
+}
+async function resolveTiersForMe(args) {
+    if (args.scopeId) {
+        const tier = await resolveCurrentTier({
+            payload: args.payload,
+            req: args.req,
+            userId: args.userId,
+            scopeId: args.scopeId,
+            locale: args.locale,
+        });
+        if (!tier)
+            return [];
+        return [
+            {
+                id: tier.id,
+                rank: tier.rank,
+                scopeId: tier.scopeId,
+                ...(tier.name ? { name: tier.name } : {}),
+                ...(tier.slug ? { slug: tier.slug } : {}),
+            },
+        ];
+    }
+    const grants = await args.payload.find({
+        collection: collectionOf('grants'),
+        depth: 0,
+        limit: 100,
+        pagination: false,
+        overrideAccess: true,
+        req: args.req,
+        where: { user: { equals: args.userId } },
+    });
+    const scopeIds = new Set();
+    for (const doc of grants.docs) {
+        scopeIds.add(relationId(doc.scope));
+    }
+    if (scopeIds.size === 0)
+        scopeIds.add(null);
+    const tiers = [];
+    for (const scopeId of scopeIds) {
+        const tier = await resolveCurrentTier({
+            payload: args.payload,
+            req: args.req,
+            userId: args.userId,
+            scopeId,
+            locale: args.locale,
+        });
+        if (!tier)
+            continue;
+        tiers.push({
+            id: tier.id,
+            rank: tier.rank,
+            scopeId: tier.scopeId,
+            ...(tier.name ? { name: tier.name } : {}),
+            ...(tier.slug ? { slug: tier.slug } : {}),
+        });
+    }
+    return tiers;
+}
+/**
+ * Current-user snapshot. Top-level Payload `find` shape for **grants**;
+ * ladder-derived `tiers` and lean `requests` ride along.
+ */
+export async function getUserProgress(args) {
+    if (!args.userId) {
+        throw new Error('getUserProgress requires userId');
+    }
+    const scopeId = args.scopeId ?? null;
+    const where = userScopeWhere(args.userId, scopeId);
+    const limit = args.paging?.limit ?? 10;
+    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([
+        args.payload.find({
+            collection: collectionOf('grants'),
+            depth: 1,
+            limit,
+            page,
+            overrideAccess: true,
+            req: args.req,
+            sort: '-completedAt',
+            where,
+            ...(locale ? { locale: locale } : {}),
+        }),
+        args.payload.find({
+            collection: collectionOf('achievementRequests'),
+            depth: 1,
+            limit: requestsLimit,
+            page: 1,
+            overrideAccess: true,
+            req: args.req,
+            sort: '-createdAt',
+            where,
+            ...(locale ? { locale: locale } : {}),
+        }),
+        resolveTiersForMe({
+            payload: args.payload,
+            req: args.req,
+            userId: args.userId,
+            scopeId,
+            locale,
+        }),
+    ]);
+    return {
+        ...mapPaginatedDocs(grants, (doc) => leanGrant(doc)),
+        tiers,
+        requests: requests.docs.map((doc) => leanRequest(doc)),
+    };
+}

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

@@ -0,0 +1,14 @@
+export { evaluateRules, evaluateRuleProgress, normalizeRuleGroup, collectAchievementCompleteRefs } from './evaluateRules';
+export type { RuleGroup, AchievementCompleteRef } from './evaluateRules';
+export { buildCatalogProgressGroups } from './buildCatalogProgressGroups';
+export type { CatalogProgressGroup, CatalogProgressItem } from './buildCatalogProgressGroups';
+export { getUserProgress } from './getUserProgress';
+export { recordEvent, recordLog, recordMetricChange, syncTierChangedLog } from './recordEvent';
+export { resolveCurrentTier } from './resolveCurrentTier';
+export type { ResolvedTier } from './resolveCurrentTier';
+export { resolveTierProgress } from './resolveTierProgress';
+export type { TierLadderProgress } from './resolveTierProgress';
+export { grantAchievement, submitAchievementRequest } from './submitAchievementRequest';
+export { reviewAchievementRequest } from './reviewAchievementRequest';
+export { validateRuleGroup, validateRuleNode } from './validateRules';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +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,iBAAiB,CAAA;AACzH,YAAY,EAAE,SAAS,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAA;AACxE,OAAO,EAAE,0BAA0B,EAAE,MAAM,8BAA8B,CAAA;AACzE,YAAY,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,MAAM,8BAA8B,CAAA;AAC7F,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAA;AACnD,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAA;AAC9F,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAA;AACzD,YAAY,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAA;AACxD,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAA;AAC3D,YAAY,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAA;AAC/D,OAAO,EAAE,gBAAgB,EAAE,wBAAwB,EAAE,MAAM,4BAA4B,CAAA;AACvF,OAAO,EAAE,wBAAwB,EAAE,MAAM,4BAA4B,CAAA;AACrE,OAAO,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAA"}

package/dist/services/achievement/index.js

@@ -0,0 +1,9 @@
+export { evaluateRules, evaluateRuleProgress, normalizeRuleGroup, collectAchievementCompleteRefs } from './evaluateRules';
+export { buildCatalogProgressGroups } from './buildCatalogProgressGroups';
+export { getUserProgress } from './getUserProgress';
+export { recordEvent, recordLog, recordMetricChange, syncTierChangedLog } from './recordEvent';
+export { resolveCurrentTier } from './resolveCurrentTier';
+export { resolveTierProgress } from './resolveTierProgress';
+export { grantAchievement, submitAchievementRequest } from './submitAchievementRequest';
+export { reviewAchievementRequest } from './reviewAchievementRequest';
+export { validateRuleGroup, validateRuleNode } from './validateRules';

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

@@ -0,0 +1,41 @@
+import type { Payload, PayloadRequest } from 'payload';
+export type RecordLogInput = {
+    payload: Payload;
+    req?: PayloadRequest;
+    userId: string;
+    scopeId?: string | null;
+    /** Log-type catalog slug (preferred) or document id. */
+    type: string;
+    actorId?: string | null;
+    /** Metric catalog slug (preferred) or document id. */
+    metric?: string;
+    /** Signed amount the metric moved (for metric.delta logs). */
+    change?: number;
+    reason?: string;
+    data?: Record<string, unknown> | null;
+};
+/** Append a catalogued occurrence to the achievement log. */
+export declare function recordLog(args: RecordLogInput): Promise<import("payload").JsonObject & import("payload").TypeWithID>;
+/** @deprecated Prefer {@link recordLog}. */
+export declare const recordEvent: typeof recordLog;
+/**
+ * Record `metric.delta`, then sync an optional `tier.changed` audit log.
+ */
+export declare function recordMetricChange(args: {
+    payload: Payload;
+    req?: PayloadRequest;
+    userId: string;
+    scopeId?: string | null;
+    metric?: string;
+    change: number;
+    reason?: string;
+    actorId?: string | null;
+}): Promise<import("payload").JsonObject & import("payload").TypeWithID>;
+/** Write `tier.changed` when the ladder-derived tier differs from the latest audit entry. */
+export declare function syncTierChangedLog(args: {
+    payload: Payload;
+    req?: PayloadRequest;
+    userId: string;
+    scopeId?: string | null;
+}): Promise<(import("payload").JsonObject & import("payload").TypeWithID) | null>;
+//# sourceMappingURL=recordEvent.d.ts.map

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

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

package/dist/services/achievement/recordEvent.js

@@ -0,0 +1,126 @@
+import { APIError } from 'payload';
+import { DEFAULT_ACHIEVEMENT_METRIC_SLUG } from '../../catalog';
+import { collectionOf } from '../../collections/helpers';
+import { eventTypeRequiresActor } from './eventTypeRequiresActor';
+import { resolveCatalogId } from './resolveCatalog';
+import { relationId } from './relationId';
+import { resolveCurrentTier } from './resolveCurrentTier';
+import { userScopeWhere } from './where';
+async function catalogId(args) {
+    return resolveCatalogId({
+        payload: args.payload,
+        req: args.req,
+        key: args.key,
+        slugOrId: args.value,
+    });
+}
+/** Append a catalogued occurrence to the achievement log. */
+export async function recordLog(args) {
+    const scopeId = args.scopeId ?? null;
+    const typeId = await catalogId({
+        payload: args.payload,
+        req: args.req,
+        key: 'eventTypes',
+        value: args.type,
+    });
+    const metricId = args.metric
+        ? await catalogId({
+            payload: args.payload,
+            req: args.req,
+            key: 'metrics',
+            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);
+        }
+    }
+    return args.payload.create({
+        collection: collectionOf('logs'),
+        data: {
+            user: args.userId,
+            scope: scopeId ?? undefined,
+            type: typeId,
+            actor: args.actorId ?? undefined,
+            metric: metricId,
+            change: args.change,
+            reason: args.reason,
+            data: args.data ?? undefined,
+        },
+        overrideAccess: true,
+        req: args.req,
+    });
+}
+/** @deprecated Prefer {@link recordLog}. */
+export const recordEvent = recordLog;
+/**
+ * Record `metric.delta`, then sync an optional `tier.changed` audit log.
+ */
+export async function recordMetricChange(args) {
+    const metricSlug = args.metric ?? DEFAULT_ACHIEVEMENT_METRIC_SLUG;
+    const scopeId = args.scopeId ?? null;
+    const log = await recordLog({
+        payload: args.payload,
+        req: args.req,
+        userId: args.userId,
+        scopeId,
+        type: 'metric.delta',
+        actorId: args.actorId,
+        metric: metricSlug,
+        change: args.change,
+        reason: args.reason,
+    });
+    await syncTierChangedLog({
+        payload: args.payload,
+        req: args.req,
+        userId: args.userId,
+        scopeId,
+    });
+    return log;
+}
+/** Write `tier.changed` when the ladder-derived tier differs from the latest audit entry. */
+export async function syncTierChangedLog(args) {
+    const scopeId = args.scopeId ?? null;
+    const current = await resolveCurrentTier({
+        payload: args.payload,
+        req: args.req,
+        userId: args.userId,
+        scopeId,
+    });
+    const typeId = await catalogId({
+        payload: args.payload,
+        req: args.req,
+        key: 'eventTypes',
+        value: 'tier.changed',
+    });
+    const latest = await args.payload.find({
+        collection: collectionOf('logs'),
+        depth: 0,
+        limit: 1,
+        overrideAccess: true,
+        req: args.req,
+        sort: '-createdAt',
+        where: {
+            and: [userScopeWhere(args.userId, scopeId), { type: { equals: typeId } }],
+        },
+    });
+    const lastTierId = relationId(latest.docs[0]?.data?.tier);
+    const currentId = current?.id ?? null;
+    if (lastTierId === currentId)
+        return null;
+    if (!currentId)
+        return null;
+    return recordLog({
+        payload: args.payload,
+        req: args.req,
+        userId: args.userId,
+        scopeId,
+        type: 'tier.changed',
+        data: {
+            tier: currentId,
+            ...(current?.slug ? { tierSlug: current.slug } : {}),
+            ...(lastTierId ? { previousTier: lastTierId } : {}),
+        },
+    });
+}

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

@@ -0,0 +1,3 @@
+/** Normalize a Payload relationship value to a string id. */
+export declare function relationId(value: unknown): string | null;
+//# sourceMappingURL=relationId.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"relationId.d.ts","sourceRoot":"","sources":["../../../src/services/achievement/relationId.ts"],"names":[],"mappings":"AAAA,6DAA6D;AAC7D,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CASxD"}

package/dist/services/achievement/relationId.js

@@ -0,0 +1,15 @@
+/** Normalize a Payload relationship value to a string id. */
+export function relationId(value) {
+    if (typeof value === 'string' && value)
+        return value;
+    if (typeof value === 'number' && Number.isFinite(value))
+        return String(value);
+    if (value && typeof value === 'object' && 'id' in value) {
+        const id = value.id;
+        if (typeof id === 'string' && id)
+            return id;
+        if (typeof id === 'number' && Number.isFinite(id))
+            return String(id);
+    }
+    return null;
+}

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

@@ -0,0 +1,14 @@
+import type { Payload, PayloadRequest } from 'payload';
+import type { AchievementCollectionKey } from '../../types';
+type CatalogKey = Extract<AchievementCollectionKey, 'eventTypes' | 'metrics'>;
+/**
+ * Resolve a catalog relationship from a slug or document id.
+ */
+export declare function resolveCatalogId(args: {
+    payload: Payload;
+    req?: PayloadRequest;
+    key: CatalogKey;
+    slugOrId: string;
+}): Promise<string>;
+export {};
+//# sourceMappingURL=resolveCatalog.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"resolveCatalog.d.ts","sourceRoot":"","sources":["../../../src/services/achievement/resolveCatalog.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,SAAS,CAAA;AAItD,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAA;AAE3D,KAAK,UAAU,GAAG,OAAO,CAAC,wBAAwB,EAAE,YAAY,GAAG,SAAS,CAAC,CAAA;AAE7E;;GAEG;AACH,wBAAsB,gBAAgB,CAAC,IAAI,EAAE;IAC3C,OAAO,EAAE,OAAO,CAAA;IAChB,GAAG,CAAC,EAAE,cAAc,CAAA;IACpB,GAAG,EAAE,UAAU,CAAA;IACf,QAAQ,EAAE,MAAM,CAAA;CACjB,GAAG,OAAO,CAAC,MAAM,CAAC,CA2BlB"}

package/dist/services/achievement/resolveCatalog.js

@@ -0,0 +1,34 @@
+import { APIError } from 'payload';
+import { collectionOf } from '../../collections/helpers';
+/**
+ * Resolve a catalog relationship from a slug or document id.
+ */
+export async function resolveCatalogId(args) {
+    const collection = collectionOf(args.key);
+    const bySlug = await args.payload.find({
+        collection,
+        depth: 0,
+        limit: 1,
+        overrideAccess: true,
+        req: args.req,
+        where: { slug: { equals: args.slugOrId } },
+    });
+    const slugId = bySlug.docs[0]?.id;
+    if (typeof slugId === 'string')
+        return slugId;
+    try {
+        const byId = (await args.payload.findByID({
+            collection,
+            id: args.slugOrId,
+            depth: 0,
+            overrideAccess: true,
+            req: args.req,
+        }));
+        if (typeof byId?.id === 'string')
+            return byId.id;
+    }
+    catch {
+        // Not a document id either.
+    }
+    throw new APIError(`Unknown ${args.key}: ${args.slugOrId}`, 400);
+}

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

@@ -0,0 +1,21 @@
+import type { Payload, PayloadRequest } from 'payload';
+export type ResolvedTier = {
+    id: string;
+    name?: string;
+    slug?: string;
+    rank: number;
+    scopeId: string | null;
+};
+/**
+ * Derive current tier by walking unlock rules in rank order (lowest first).
+ * Empty unlock rules pass. `tier-at-least` uses the rank unlocked so far on this walk.
+ */
+export declare function resolveCurrentTier(args: {
+    payload: Payload;
+    req?: PayloadRequest;
+    userId: string;
+    scopeId?: string | null;
+    /** Content locale for localized tier names (falls back to `req.locale`). */
+    locale?: string;
+}): Promise<ResolvedTier | null>;
+//# sourceMappingURL=resolveCurrentTier.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"resolveCurrentTier.d.ts","sourceRoot":"","sources":["../../../src/services/achievement/resolveCurrentTier.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,SAAS,CAAA;AAMtD,MAAM,MAAM,YAAY,GAAG;IACzB,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;CACvB,CAAA;AAWD;;;GAGG;AACH,wBAAsB,kBAAkB,CAAC,IAAI,EAAE;IAC7C,OAAO,EAAE,OAAO,CAAA;IAChB,GAAG,CAAC,EAAE,cAAc,CAAA;IACpB,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACvB,4EAA4E;IAC5E,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAoD/B"}

package/dist/services/achievement/resolveCurrentTier.js

@@ -0,0 +1,51 @@
+import { collectionOf } from '../../collections/helpers';
+import { evaluateRules } from './evaluateRules';
+import { relationId } from './relationId';
+/**
+ * Derive current tier by walking unlock rules in rank order (lowest first).
+ * Empty unlock rules pass. `tier-at-least` uses the rank unlocked so far on this walk.
+ */
+export async function resolveCurrentTier(args) {
+    if (!args.userId)
+        return null;
+    const scopeId = args.scopeId ?? null;
+    const locale = args.locale ?? (args.req?.locale || undefined);
+    const where = scopeId
+        ? { or: [{ scope: { equals: scopeId } }, { scope: { exists: false } }] }
+        : undefined;
+    const result = await args.payload.find({
+        collection: collectionOf('tiers'),
+        depth: 0,
+        limit: 100,
+        pagination: false,
+        overrideAccess: true,
+        req: args.req,
+        sort: 'rank',
+        ...(locale ? { locale: locale } : {}),
+        ...(where ? { where } : {}),
+    });
+    const tiers = [...result.docs].sort((a, b) => Number(a.rank ?? 0) - Number(b.rank ?? 0));
+    // evaluateRules requires a PayloadRequest; synthesize a minimal one when only payload is passed.
+    const req = (args.req ?? { payload: args.payload });
+    let current = null;
+    for (const tier of tiers) {
+        const unlocked = await evaluateRules({
+            payload: args.payload,
+            req,
+            rules: tier.unlockRules,
+            userId: args.userId,
+            scopeId,
+            ladderRank: current?.rank ?? null,
+        });
+        if (!unlocked)
+            continue;
+        current = {
+            id: String(tier.id),
+            rank: Number(tier.rank ?? 0),
+            scopeId: relationId(tier.scope),
+            ...(typeof tier.name === 'string' && tier.name ? { name: tier.name } : {}),
+            ...(typeof tier.slug === 'string' && tier.slug ? { slug: tier.slug } : {}),
+        };
+    }
+    return current;
+}

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

@@ -0,0 +1,35 @@
+import type { Payload, PayloadRequest } from 'payload';
+import { type ResolvedTier } from './resolveCurrentTier';
+export type TierLadderProgress = {
+    current: ResolvedTier | null;
+    next: ResolvedTier | null;
+    /** 0..1 progress toward unlocking `next` (1 when there is no next tier). */
+    progressTowardNext: number;
+    /**
+     * 0..1 position along the ordered ladder for UI tracks:
+     * `(currentIndex + progressTowardNext) / (tierCount - 1)`.
+     * When no current tier yet, uses `progressTowardNext / (tierCount - 1)`.
+     */
+    ladderProgress: number;
+    tiers: Array<{
+        id: string;
+        name?: string;
+        slug?: string;
+        rank: number;
+    }>;
+};
+/**
+ * Current tier, next tier, and fractional progress toward the next unlock rules.
+ *
+ * Progress uses {@link evaluateRuleProgress}: AND averages requirement children equally
+ * (`tier-at-least` is a gate and is skipped). Nested `achievement-complete` rules roll
+ * up eligibility progress when the child is not yet granted.
+ */
+export declare function resolveTierProgress(args: {
+    payload: Payload;
+    req?: PayloadRequest;
+    userId: string;
+    scopeId?: string | null;
+    locale?: string;
+}): Promise<TierLadderProgress>;
+//# sourceMappingURL=resolveTierProgress.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"resolveTierProgress.d.ts","sourceRoot":"","sources":["../../../src/services/achievement/resolveTierProgress.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,SAAS,CAAA;AAKtD,OAAO,EAAsB,KAAK,YAAY,EAAE,MAAM,sBAAsB,CAAA;AAE5E,MAAM,MAAM,kBAAkB,GAAG;IAC/B,OAAO,EAAE,YAAY,GAAG,IAAI,CAAA;IAC5B,IAAI,EAAE,YAAY,GAAG,IAAI,CAAA;IACzB,4EAA4E;IAC5E,kBAAkB,EAAE,MAAM,CAAA;IAC1B;;;;OAIG;IACH,cAAc,EAAE,MAAM,CAAA;IACtB,KAAK,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CACzE,CAAA;AAWD;;;;;;GAMG;AACH,wBAAsB,mBAAmB,CAAC,IAAI,EAAE;IAC9C,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;CAChB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAoG9B"}

package/dist/services/achievement/resolveTierProgress.js

@@ -0,0 +1,99 @@
+import { collectionOf } from '../../collections/helpers';
+import { evaluateRuleProgress } from './evaluateRules';
+import { relationId } from './relationId';
+import { resolveCurrentTier } from './resolveCurrentTier';
+/**
+ * Current tier, next tier, and fractional progress toward the next unlock rules.
+ *
+ * Progress uses {@link evaluateRuleProgress}: AND averages requirement children equally
+ * (`tier-at-least` is a gate and is skipped). Nested `achievement-complete` rules roll
+ * up eligibility progress when the child is not yet granted.
+ */
+export async function resolveTierProgress(args) {
+    if (!args.userId) {
+        return { current: null, next: null, progressTowardNext: 0, ladderProgress: 0, tiers: [] };
+    }
+    const scopeId = args.scopeId ?? null;
+    const locale = args.locale ?? (args.req?.locale || undefined);
+    const where = scopeId
+        ? { or: [{ scope: { equals: scopeId } }, { scope: { exists: false } }] }
+        : undefined;
+    const result = await args.payload.find({
+        collection: collectionOf('tiers'),
+        depth: 0,
+        limit: 100,
+        pagination: false,
+        overrideAccess: true,
+        req: args.req,
+        sort: 'rank',
+        ...(locale ? { locale: locale } : {}),
+        ...(where ? { where } : {}),
+    });
+    const ordered = [...result.docs].sort((a, b) => Number(a.rank ?? 0) - Number(b.rank ?? 0));
+    const tiers = ordered.map((tier) => ({
+        id: String(tier.id),
+        rank: Number(tier.rank ?? 0),
+        ...(typeof tier.name === 'string' && tier.name ? { name: tier.name } : {}),
+        ...(typeof tier.slug === 'string' && tier.slug ? { slug: tier.slug } : {}),
+    }));
+    if (ordered.length === 0) {
+        return { current: null, next: null, progressTowardNext: 0, ladderProgress: 0, tiers };
+    }
+    const current = await resolveCurrentTier({
+        payload: args.payload,
+        req: args.req,
+        userId: args.userId,
+        scopeId,
+        locale,
+    });
+    const currentIndex = current
+        ? ordered.findIndex((tier) => String(tier.id) === current.id)
+        : -1;
+    const nextDoc = currentIndex >= 0 && currentIndex < ordered.length - 1
+        ? ordered[currentIndex + 1]
+        : currentIndex < 0
+            ? ordered[0]
+            : undefined;
+    const req = args.req ?? { payload: args.payload };
+    let progressTowardNext = 1;
+    if (nextDoc) {
+        progressTowardNext = await evaluateRuleProgress({
+            payload: args.payload,
+            req,
+            rules: nextDoc.unlockRules,
+            userId: args.userId,
+            scopeId,
+            ladderRank: current?.rank ?? null,
+        });
+    }
+    const next = nextDoc
+        ? {
+            id: String(nextDoc.id),
+            rank: Number(nextDoc.rank ?? 0),
+            scopeId: relationId(nextDoc.scope),
+            ...(typeof nextDoc.name === 'string' && nextDoc.name ? { name: nextDoc.name } : {}),
+            ...(typeof nextDoc.slug === 'string' && nextDoc.slug ? { slug: nextDoc.slug } : {}),
+        }
+        : null;
+    const lastIndex = Math.max(1, ordered.length - 1);
+    let ladderProgress;
+    if (ordered.length < 2) {
+        ladderProgress = current || progressTowardNext >= 1 ? 1 : progressTowardNext;
+    }
+    else if (!next) {
+        ladderProgress = 1;
+    }
+    else if (currentIndex < 0) {
+        ladderProgress = progressTowardNext / lastIndex;
+    }
+    else {
+        ladderProgress = (currentIndex + progressTowardNext) / lastIndex;
+    }
+    return {
+        current,
+        next,
+        progressTowardNext,
+        ladderProgress: Math.max(0, Math.min(1, ladderProgress)),
+        tiers,
+    };
+}

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

@@ -0,0 +1,11 @@
+import type { PayloadRequest } from 'payload';
+/**
+ * Approve or reject via collection update. Grant runs in afterChange when approved.
+ */
+export declare function reviewAchievementRequest(args: {
+    req: PayloadRequest;
+    requestId: string;
+    decision: 'approved' | 'rejected';
+    note?: string;
+}): Promise<import("payload").JsonObject & import("payload").TypeWithID>;
+//# sourceMappingURL=reviewAchievementRequest.d.ts.map