@dappermountain/payload-plugin-achievements 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Dapper Mountain
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,319 @@
+# `@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.
+
+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.
+
+## Why this plugin
+
+- **Admin-owned catalog** — Admins create achievements, tiers, metrics, and event types in Payload without a deploy.
+- **Composable rules** — Nested AND/OR trees with built-in leaf types (`tier-at-least`, `achievement-complete`, `metric-minimum`, `event-count`) plus host-defined rule types.
+- **Derived progress** — Ladder position and next-tier fill come from evaluating the same rules that unlock ranks. No fragile “progress” documents to keep in sync.
+- **Request → review → grant** — Users can request achievements; reviewers approve or reject; composed achievements can auto-grant when completion rules pass.
+- **Append-only history** — Logs capture grants, metric deltas, tier changes, and custom event kinds for audits and analytics.
+- **Multi-tenant ready** — Optional `scope` (tenant / workspace / org) on catalog rows and user progress.
+- **Host-friendly** — Prefixable collection slugs, Form Builder–style overrides, injectable review policy, and server helpers for recording events from hooks and jobs.
+
+## Requirements
+
+- Payload `^3.88`
+- `@payloadcms/ui` `^3.88`
+- React `^19`
+
+## Install
+
+```bash
+npm install @dappermountain/payload-plugin-achievements
+# or: pnpm add / yarn add / bun add
+```
+
+## Quick start
+
+```ts
+import { buildConfig } from 'payload'
+import { achievementPlugin } from '@dappermountain/payload-plugin-achievements'
+
+export default buildConfig({
+  // ...
+  plugins: [
+    achievementPlugin({
+      usersCollectionSlug: 'users',
+      canReview: (user, scopeId) => {
+        // Return true when this user may edit catalogs and approve requests
+        // for the given scope (or null for unscoped / global).
+        return Boolean(user?.roles?.includes('admin'))
+      },
+      // Optional: scope catalog + progress to a tenant collection
+      // scope: { collection: 'tenants', relationField: 'scope' },
+    }),
+  ],
+})
+```
+
+After installing, regenerate the Admin import map so conditional log fields resolve:
+
+```bash
+payload generate:importmap
+```
+
+Your app still owns schema and migrations — run `payload migrate` (or your usual migrate flow) as you would for any new collections.
+
+Seed the built-in engine catalog (points metric + system event types) once:
+
+```ts
+import { seedAchievementCatalog } from '@dappermountain/payload-plugin-achievements'
+
+await seedAchievementCatalog(payload)
+```
+
+## What you get
+
+### Collections
+
+Slugs are prefixed with `achievement-` by default so they don’t collide with your own collections.
+
+| Config key | Default slug | Purpose |
+| --- | --- | --- |
+| `metrics` | `achievement-metrics` | Named scores (points, streaks, …). Totals are derived by summing `metric.delta` logs. |
+| `eventTypes` | `achievement-event-types` | Kinds of log entries you can count or require. |
+| `tiers` | `achievement-tiers` | Ordered ladder steps with unlock rules. |
+| `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. |
+
+**System catalog rows** (seeded by `seedAchievementCatalog`) are protected from deletion and slug changes:
+
+| Slug | Role |
+| --- | --- |
+| `points` | Default metric |
+| `metric.delta` | Metric change log type (requires metric + change amount) |
+| `achievement.granted` | Written when a grant is created |
+| `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.
+
+### Rules engine
+
+Unlock (tiers), eligibility, and completion (achievements) share the same rule tree shape:
+
+- Top-level empty list → everyone passes
+- Nested groups → AND (“all of these”) or OR (“any of these”)
+- 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`):
+
+| Combinator / leaf | Progress behavior |
+| --- | --- |
+| AND | Equal average of *requirement* children |
+| OR | Best child (max) |
+| `tier-at-least` | Gate — skipped in AND averages |
+| `event-count` / `metric-minimum` | Fraction of the target |
+| `achievement-complete` | `1` if granted; otherwise rolls up that achievement’s completion (or eligibility) rules |
+
+**Eligibility rules** gate who may request an achievement. **Completion rules** define what a composed achievement is made of. When `requiresReview` is false and completion rules pass, the parent can auto-grant. Cycles in nested achievement graphs are ignored.
+
+### Access model
+
+- **`canReview`** — Required for privileged writes (catalogs, grants, logs, approving requests). If omitted, those writes are denied.
+- User requests still go through normal collection access and eligibility hooks.
+- Server helpers (`recordLog`, `recordMetricChange`, `grantAchievement`, `resolveCurrentTier`, …) run with `overrideAccess: true`. Call them only from trusted server code (hooks, jobs, locked-down endpoints).
+
+### Localization
+
+When your Payload config enables **`localization`**, catalog display fields are already `localized: true`:
+
+| Collection | Localized | Not localized |
+| --- | --- | --- |
+| Achievements / tiers | `name`, `description` | `slug`, rules, flags |
+| Metrics / event types | `name` | `slug`, system flags |
+
+UI chrome and validation messages ship in English. Application UI copy stays in your app’s i18n layer — the plugin does not inject host translation dictionaries. Seed extra locales yourself after the English system catalog is in place.
+
+## Configuration reference
+
+```ts
+achievementPlugin({
+  enabled?: boolean
+  usersCollectionSlug?: string
+  canReview?: (user, scopeId) => boolean | Promise<boolean>
+  scope?: { collection: string; relationField?: string }
+  mediaCollection?: string
+  slugPrefix?: string // deprecated — prefer collections.prefix
+  collections?: {
+    prefix?: string
+    adminGroup?: string | false
+    slugs?: Partial<Record<AchievementCollectionKey, string>>
+    overrides?: Partial<Record<AchievementCollectionKey, AchievementCollectionOverride>>
+  }
+  users?: { includeJoins?: boolean }
+  endpoints?: { me?: string | false }
+  extensions?: { ruleTypes?: AchievementRuleType[] }
+})
+```
+
+### Core options
+
+| Option | Default | Notes |
+| --- | --- | --- |
+| `enabled` | `true` | Set `false` to leave the plugin installed but inactive (no collections / endpoints merged). |
+| `usersCollectionSlug` | `'users'` | Users collection the plugin relates to (grants, requests, joins). |
+| `canReview` | _(denied)_ | **Important.** Without this, users cannot manage catalogs or approve requests. Receives `(user, scopeId)` where `scopeId` may be `null`. |
+| `scope` | _(none)_ | Multi-tenant hook-up. `collection` is the relation target (e.g. `'tenants'`). `relationField` defaults to `'scope'`. Adds an optional scope field across plugin collections. |
+| `mediaCollection` | _(none)_ | When set (e.g. `'media'`), tiers get an optional upload field for ladder badge images. Icon string keys still work without this. |
+
+### `collections`
+
+| Option | Default | Notes |
+| --- | --- | --- |
+| `prefix` | `'achievement'` | Prefix for default slugs → REST paths and DB table names (`achievement-tiers`, …). |
+| `adminGroup` | `'Achievements'` | Admin sidebar group. Pass `false` to leave collections ungrouped. |
+| `slugs` | _(derived)_ | Absolute slug overrides per collection key (ignores `prefix` for that key). |
+| `overrides` | _(none)_ | Per-collection patches: `access`, `admin`, `hooks`, `labels`. Access keys replace; hook arrays **append after** plugin hooks; `admin` / `labels` merge shallowly. |
+
+Example override (notify after a grant is created via request approval):
+
+```ts
+achievementPlugin({
+  canReview,
+  collections: {
+    overrides: {
+      achievementRequests: {
+        hooks: {
+          afterChange: [
+            async ({ doc, previousDoc }) => {
+              if (doc.status === 'approved' && previousDoc?.status !== 'approved') {
+                // notify, analytics, …
+              }
+            },
+          ],
+        },
+      },
+    },
+  },
+})
+```
+
+### `users`
+
+| Option | Default | Notes |
+| --- | --- | --- |
+| `includeJoins` | `true` | Injects an `achievements` group on the users collection with joins to grants and requests. Set `false` if you own that UI yourself. |
+
+### `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. |
+
+Query params: `scope`, `limit`, `page`, `requestsLimit`.
+
+### `extensions.ruleTypes`
+
+Register custom rule evaluators merged with the built-ins:
+
+```ts
+achievementPlugin({
+  canReview,
+  extensions: {
+    ruleTypes: [
+      {
+        type: 'host.custom-check',
+        evaluate: async ({ rule, userId, payload, req }) => {
+          // return true when the rule passes
+          return true
+        },
+        // optional: progress: async () => 0.5,
+        // optional: progressRole: 'requirement' | 'gate',
+      },
+    ],
+  },
+})
+```
+
+## Server helpers
+
+Use these from hooks, jobs, and trusted endpoints — not from the public client:
+
+```ts
+import {
+  recordLog,
+  recordMetricChange,
+  grantAchievement,
+  resolveCurrentTier,
+  resolveTierProgress,
+  getUserProgress,
+  submitAchievementRequest,
+  reviewAchievementRequest,
+} from '@dappermountain/payload-plugin-achievements'
+
+await recordLog({ payload, userId, scopeId, type: 'host.custom-kind', actorId })
+await recordMetricChange({ payload, userId, scopeId, metric: 'points', change: 10 })
+const tier = await resolveCurrentTier({ payload, userId, scopeId })
+```
+
+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.
+
+## REST surface
+
+| Goal | Request |
+| --- | --- |
+| Current user snapshot | `GET /api/achievements/me?scope=<scopeId>&limit=10&page=1` |
+| 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" }` |
+| Browse catalogs | `GET /api/achievement-event-types`, `GET /api/achievement-metrics`, … |
+
+Exact collection paths follow your `collections.prefix` / `slugs` settings.
+
+## Seeding
+
+```ts
+import {
+  seedAchievementCatalog,
+  seedAchievements,
+} from '@dappermountain/payload-plugin-achievements'
+
+await seedAchievementCatalog(payload) // system metrics + event types (English)
+
+await seedAchievements(payload, {
+  eventTypes: [{ name: 'Custom kind', slug: 'host.custom-kind', requiresActor: true }],
+  metrics: [{ name: 'Streak days', slug: 'streak-days' }],
+  tiers: [
+    {
+      name: 'Prospect',
+      slug: 'prospect',
+      rank: 0,
+      unlockRules: [], // open
+    },
+  ],
+  achievements: [
+    {
+      name: 'First steps',
+      slug: 'first-steps',
+      requiresReview: false,
+      completionRules: [{ type: 'metric-minimum', metricSlug: 'points', minimum: 10 }],
+    },
+  ],
+})
+```
+
+`name` / `description` accept a string (default locale) or a locale map (`{ en: '…', es: '…' }`) when Payload localization is enabled. Prefer seeding extra locales in the host after the English system catalog exists.
+
+## License
+
+MIT © Dapper Mountain
+
+## Agent context (Cursor)
+
+This repo vendors AI agent rules and skills under [`.agents/`](.agents/). See [`AGENTS.md`](AGENTS.md).
+
+```bash
+bun install
+bun run agents:sync
+bun run skills:install
+```
+
+Dev dependencies: [`@dappermountain/agent-practices`](https://www.npmjs.com/package/@dappermountain/agent-practices), [`@dappermountain/agent-payload`](https://www.npmjs.com/package/@dappermountain/agent-payload). Run `agents:sync` after install or upgrade so rules land under `.agents/`.

package/dist/access/helpers/index.d.ts

@@ -0,0 +1,9 @@
+import type { Access, AccessArgs, PayloadRequest, Where } from 'payload';
+type AccessResult = boolean | Where;
+export type AccessFn = (args: AccessArgs) => AccessResult | Promise<AccessResult>;
+export declare const allowAll: Access;
+export declare const denyAll: Access;
+export declare function requireOne(...fns: AccessFn[]): Access;
+export declare function getUserId(req: PayloadRequest): string | null;
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/access/helpers/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/access/helpers/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,cAAc,EAAE,KAAK,EAAE,MAAM,SAAS,CAAA;AAExE,KAAK,YAAY,GAAG,OAAO,GAAG,KAAK,CAAA;AAEnC,MAAM,MAAM,QAAQ,GAAG,CAAC,IAAI,EAAE,UAAU,KAAK,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC,CAAA;AAEjF,eAAO,MAAM,QAAQ,EAAE,MAAmB,CAAA;AAE1C,eAAO,MAAM,OAAO,EAAE,MAAoB,CAAA;AAE1C,wBAAgB,UAAU,CAAC,GAAG,GAAG,EAAE,QAAQ,EAAE,GAAG,MAAM,CASrD;AAED,wBAAgB,SAAS,CAAC,GAAG,EAAE,cAAc,GAAG,MAAM,GAAG,IAAI,CAO5D"}

package/dist/access/helpers/index.js

@@ -0,0 +1,25 @@
+export const allowAll = () => true;
+export const denyAll = () => false;
+export function requireOne(...fns) {
+    return async (args) => {
+        for (const fn of fns) {
+            const result = await fn(args);
+            if (result === true)
+                return true;
+            if (result && typeof result === 'object')
+                return result;
+        }
+        return false;
+    };
+}
+export function getUserId(req) {
+    const user = req.user;
+    if (!user || typeof user !== 'object')
+        return null;
+    const id = user.id;
+    if (typeof id === 'string' && id)
+        return id;
+    if (typeof id === 'number' && Number.isFinite(id))
+        return String(id);
+    return null;
+}

package/dist/access/index.d.ts

@@ -0,0 +1,3 @@
+export * from './helpers/index';
+export * from './roles/index';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/access/index.ts"],"names":[],"mappings":"AAAA,cAAc,iBAAiB,CAAA;AAC/B,cAAc,eAAe,CAAA"}

package/dist/access/index.js

@@ -0,0 +1,2 @@
+export * from './helpers/index';
+export * from './roles/index';

package/dist/access/roles/index.d.ts

@@ -0,0 +1,15 @@
+import type { AccessArgs } from 'payload';
+import type { AchievementCollectionKey } from '../../types';
+/** Authenticated user may read/write rows tied to themselves. */
+export declare const isSelfUser: (userRelationField?: string) => ({ req, data }: AccessArgs) => boolean | {
+    [x: string]: {
+        equals: string;
+    };
+};
+/**
+ * Host `canReview` policy. When unset, privileged writes are denied (safe default).
+ * Passes document scope when available (from `data.scope` or loaded by id).
+ */
+export declare const isReviewer: (collectionKey?: AchievementCollectionKey) => (args: AccessArgs) => Promise<boolean>;
+export declare const isAuthenticated: ({ req }: AccessArgs) => boolean;
+//# sourceMappingURL=index.d.ts.map

package/dist/access/roles/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/access/roles/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAA;AAEzC,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAA;AAM3D,iEAAiE;AACjE,eAAO,MAAM,UAAU,GACpB,0BAA0B,MAC1B,eAAe,UAAU;;;;CAgBzB,CAAA;AA0BH;;;GAGG;AACH,eAAO,MAAM,UAAU,GACpB,gBAAgB,wBAAwB,MAClC,MAAM,UAAU,qBAMtB,CAAA;AAEH,eAAO,MAAM,eAAe,GAAI,SAAS,UAAU,YAAsB,CAAA"}

package/dist/access/roles/index.js

@@ -0,0 +1,55 @@
+import { collectionOf } from '../../collections/helpers';
+import { getAchievementOptions } from '../../options-store';
+import { relationId } from '../../services/achievement/relationId';
+import { getUserId } from '../helpers/index';
+/** Authenticated user may read/write rows tied to themselves. */
+export const isSelfUser = (userRelationField = 'user') => ({ req, data }) => {
+    const userId = getUserId(req);
+    if (!userId)
+        return false;
+    if (data && typeof data === 'object' && userRelationField in data) {
+        const related = data[userRelationField];
+        const relatedId = typeof related === 'object' && related && 'id' in related
+            ? String(related.id)
+            : String(related);
+        return relatedId === userId;
+    }
+    return {
+        [userRelationField]: { equals: userId },
+    };
+};
+async function scopeIdForAccess(args, collectionKey) {
+    const fromData = relationId(args.data?.scope);
+    if (fromData)
+        return fromData;
+    if (!args.id || !collectionKey || !args.req?.payload)
+        return null;
+    try {
+        const doc = (await args.req.payload.findByID({
+            collection: collectionOf(collectionKey),
+            id: String(args.id),
+            depth: 0,
+            overrideAccess: true,
+            req: args.req,
+            select: { scope: true },
+        }));
+        return relationId(doc?.scope);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Host `canReview` policy. When unset, privileged writes are denied (safe default).
+ * Passes document scope when available (from `data.scope` or loaded by id).
+ */
+export const isReviewer = (collectionKey) => async (args) => {
+    if (!args.req.user)
+        return false;
+    const { canReview } = getAchievementOptions();
+    if (!canReview)
+        return false;
+    const scopeId = await scopeIdForAccess(args, collectionKey);
+    return Boolean(await canReview(args.req.user, scopeId));
+};
+export const isAuthenticated = ({ req }) => Boolean(req.user);

package/dist/admin/ActorField.d.ts

@@ -0,0 +1,9 @@
+import type { RelationshipFieldClientProps } from 'payload';
+import React from 'react';
+type ActorFieldProps = RelationshipFieldClientProps & {
+    eventTypesSlug: string;
+};
+/** Relationship field that only renders when the selected event type requires an actor. */
+export declare function ActorField(props: ActorFieldProps): React.JSX.Element | null;
+export {};
+//# sourceMappingURL=ActorField.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ActorField.d.ts","sourceRoot":"","sources":["../../src/admin/ActorField.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,SAAS,CAAA;AAE3D,OAAO,KAAoB,MAAM,OAAO,CAAA;AAIxC,KAAK,eAAe,GAAG,4BAA4B,GAAG;IACpD,cAAc,EAAE,MAAM,CAAA;CACvB,CAAA;AAED,2FAA2F;AAC3F,wBAAgB,UAAU,CAAC,KAAK,EAAE,eAAe,4BAchD"}

package/dist/admin/ActorField.js

@@ -0,0 +1,19 @@
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+import { RelationshipField, useField } from '@payloadcms/ui';
+import { useEffect } from 'react';
+import { useEventTypeFlags } from './useEventTypeFlags';
+/** Relationship field that only renders when the selected event type requires an actor. */
+export function ActorField(props) {
+    const { eventTypesSlug, ...fieldArgs } = props;
+    const { requiresActor } = useEventTypeFlags(eventTypesSlug);
+    const { setValue, value } = useField({ path: fieldArgs.path });
+    useEffect(() => {
+        if (!requiresActor && value != null && value !== '') {
+            setValue(null);
+        }
+    }, [requiresActor, setValue, value]);
+    if (!requiresActor)
+        return null;
+    return _jsx(RelationshipField, { ...fieldArgs });
+}

package/dist/admin/MetricChangeField.d.ts

@@ -0,0 +1,9 @@
+import type { NumberFieldClientProps } from 'payload';
+import React from 'react';
+type MetricChangeFieldProps = NumberFieldClientProps & {
+    eventTypesSlug: string;
+};
+/** Signed change amount — only when the type adjusts a metric and a metric is selected. */
+export declare function MetricChangeField(props: MetricChangeFieldProps): React.JSX.Element | null;
+export {};
+//# sourceMappingURL=MetricChangeField.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"MetricChangeField.d.ts","sourceRoot":"","sources":["../../src/admin/MetricChangeField.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,SAAS,CAAA;AAErD,OAAO,KAAoB,MAAM,OAAO,CAAA;AAIxC,KAAK,sBAAsB,GAAG,sBAAsB,GAAG;IACrD,cAAc,EAAE,MAAM,CAAA;CACvB,CAAA;AAED,2FAA2F;AAC3F,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,sBAAsB,4BAgB9D"}

package/dist/admin/MetricChangeField.js

@@ -0,0 +1,21 @@
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+import { NumberField, useField, useFormFields } from '@payloadcms/ui';
+import { useEffect } from 'react';
+import { useEventTypeFlags } from './useEventTypeFlags';
+/** Signed change amount — only when the type adjusts a metric and a metric is selected. */
+export function MetricChangeField(props) {
+    const { eventTypesSlug, ...fieldArgs } = props;
+    const { requiresMetric } = useEventTypeFlags(eventTypesSlug);
+    const metricValue = useFormFields(([fields]) => fields.metric?.value);
+    const { setValue, value } = useField({ path: fieldArgs.path });
+    const show = requiresMetric && Boolean(metricValue);
+    useEffect(() => {
+        if (!show && value != null && value !== '') {
+            setValue(null);
+        }
+    }, [show, setValue, value]);
+    if (!show)
+        return null;
+    return _jsx(NumberField, { ...fieldArgs });
+}

package/dist/admin/MetricField.d.ts

@@ -0,0 +1,9 @@
+import type { RelationshipFieldClientProps } from 'payload';
+import React from 'react';
+type MetricFieldProps = RelationshipFieldClientProps & {
+    eventTypesSlug: string;
+};
+/** Metric relationship — only for event types that adjust a score. */
+export declare function MetricField(props: MetricFieldProps): React.JSX.Element | null;
+export {};
+//# sourceMappingURL=MetricField.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"MetricField.d.ts","sourceRoot":"","sources":["../../src/admin/MetricField.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,SAAS,CAAA;AAE3D,OAAO,KAAoB,MAAM,OAAO,CAAA;AAIxC,KAAK,gBAAgB,GAAG,4BAA4B,GAAG;IACrD,cAAc,EAAE,MAAM,CAAA;CACvB,CAAA;AAED,sEAAsE;AACtE,wBAAgB,WAAW,CAAC,KAAK,EAAE,gBAAgB,4BAelD"}

package/dist/admin/MetricField.js

@@ -0,0 +1,23 @@
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+import { RelationshipField, useField } from '@payloadcms/ui';
+import { useEffect } from 'react';
+import { useEventTypeFlags } from './useEventTypeFlags';
+/** Metric relationship — only for event types that adjust a score. */
+export function MetricField(props) {
+    const { eventTypesSlug, ...fieldArgs } = props;
+    const { requiresMetric } = useEventTypeFlags(eventTypesSlug);
+    const metric = useField({ path: fieldArgs.path });
+    const change = useField({ path: 'change' });
+    useEffect(() => {
+        if (requiresMetric)
+            return;
+        if (metric.value != null && metric.value !== '')
+            metric.setValue(null);
+        if (change.value != null && change.value !== '')
+            change.setValue(null);
+    }, [requiresMetric, metric.value, metric.setValue, change.value, change.setValue]);
+    if (!requiresMetric)
+        return null;
+    return _jsx(RelationshipField, { ...fieldArgs });
+}

package/dist/admin/useEventTypeFlags.d.ts

@@ -0,0 +1,7 @@
+export type EventTypeFlags = {
+    requiresActor: boolean;
+    requiresMetric: boolean;
+};
+/** Resolve event-type flags for the selected `type` field (fetch when only an id is present). */
+export declare function useEventTypeFlags(eventTypesSlug: string): EventTypeFlags;
+//# sourceMappingURL=useEventTypeFlags.d.ts.map

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

@@ -0,0 +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"}

package/dist/admin/useEventTypeFlags.js

@@ -0,0 +1,68 @@
+'use client';
+import { useConfig, useFormFields } from '@payloadcms/ui';
+import { useEffect, useMemo, useState } from 'react';
+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;
+}
+function flagsFromValue(typeValue) {
+    if (!typeValue || typeof typeValue !== 'object')
+        return null;
+    if (!('requiresActor' in typeValue || 'requiresMetric' in typeValue || 'slug' in typeValue)) {
+        return null;
+    }
+    const row = typeValue;
+    return {
+        requiresActor: Boolean(row.requiresActor),
+        requiresMetric: Boolean(row.requiresMetric) || row.slug === 'metric.delta',
+    };
+}
+const empty = { requiresActor: false, requiresMetric: false };
+/** Resolve event-type flags for the selected `type` field (fetch when only an id is present). */
+export function useEventTypeFlags(eventTypesSlug) {
+    const { config } = useConfig();
+    const typeValue = useFormFields(([fields]) => fields.type?.value);
+    const typeId = useMemo(() => relationId(typeValue), [typeValue]);
+    const known = flagsFromValue(typeValue);
+    const [flags, setFlags] = useState(known ?? empty);
+    useEffect(() => {
+        if (known) {
+            setFlags(known);
+            return;
+        }
+        if (!typeId || !eventTypesSlug) {
+            setFlags(empty);
+            return;
+        }
+        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`;
+        void fetch(url, { credentials: 'include', signal: controller.signal })
+            .then(async (res) => {
+            if (!res.ok) {
+                setFlags(empty);
+                return;
+            }
+            const doc = await res.json();
+            setFlags(flagsFromValue(doc) ?? empty);
+        })
+            .catch((err) => {
+            if (err && typeof err === 'object' && 'name' in err && err.name === 'AbortError')
+                return;
+            setFlags(empty);
+        });
+        return () => controller.abort();
+    }, [known, typeId, eventTypesSlug, config.routes?.api, config.serverURL]);
+    return flags;
+}