@dappermountain/payload-plugin-achievements 0.6.0 → 1.0.0-beta.1

package/README.md

@@ -1,31 +1,46 @@
 # `@dappermountain/payload-plugin-achievements`
 
-Achievements, ranks, points, and an activity log for Payload CMS — all configured in Admin.
+Achievements, tiers, points, and an activity log for Payload CMS — all configured in Admin.
 
-You describe what people can earn and what has to happen first. Your app records those happenings. The plugin derives the current rank and progress from that history, so the ladder stays in step with real activity.
+You describe what people can earn and what has to happen first. Your app records those happenings. The plugin derives the current tier and progress from that history, so the ladder stays in step with real activity.
 
 ## What you get
 
 - **A catalog in Admin.** Achievements, tiers, metrics, event types, and reactions. Editors change rules there.
 - **Composable rules.** Nested all-of / any-of trees, plus your own leaf types.
-- **Derived ranks.** Current tier and next-tier fill come from the same unlock rules.
+- **Derived tiers.** Current tier and next-tier fill come from the same unlock rules.
 - **Request and review.** Members can ask for an achievement; reviewers approve or reject. Composed achievements can grant themselves when their completion rules pass.
-- **An activity log.** Grants, score changes, rank moves, and your own event kinds.
+- **An activity log.** Grants, score changes, tier moves, and your own event kinds.
 - **Optional multi-tenant scope.** Point `scope` at your tenants / workspaces / orgs collection.
 - **Host hooks.** Prefixable slugs, collection overrides, a review policy you inject, and server helpers for trusted code.
 
-## Requirements
+## Payload version support
 
-- Payload `^3.89`
-- `@payloadcms/ui` `^3.89`
-- `@payloadcms/richtext-lexical` `^3.89`
+| Plugin line | Payload | Notes |
+| ----------- | ------- | ----- |
+| **`1.x`** (this package — e.g. `1.0.0-beta.1`) | **4** (`^4.0.0-beta.1` / `^4.0.0`) | Current line. Opt out of P4 default versions/authorship on high-churn collections. |
+| **`0.6.x`** | **3** (`^3.89`) | Last Payload 3 line. Same product features (reactions, composites, etc.). Stay on `0.6.x` until you upgrade the host to Payload 4. |
+
+One published version cannot peer both Payload majors (Admin field types and collection defaults diverge). Pick the line that matches your host.
+
+## Requirements (1.x)
+
+- Payload `^4.0.0-beta.1` / `^4.0.0`
+- `@payloadcms/ui` (same train as Payload)
+- `@payloadcms/richtext-lexical` (same train as Payload)
 - `lucide-react` `^0.543`
 - React `^19`
 
+Plugin collections opt out of Payload 4’s default versions and authorship (append-only logs and high-churn grants should not grow `_versions` tables).
+
 ## Install
 
 ```bash
-bun add @dappermountain/payload-plugin-achievements
+# Payload 4 hosts
+bun add @dappermountain/payload-plugin-achievements@^1.0.0-beta.1
+
+# Payload 3 hosts (stay on the 0.6 line)
+bun add @dappermountain/payload-plugin-achievements@0.6
 ```
 
 `npm` and other clients work too. Next.js hosts should list the package in `transpilePackages` so the `'use client'` Admin fields compile.
@@ -63,7 +78,7 @@ Think of four layers:
 
 1. **Catalog** — named things in Admin (event types, metrics, tiers, achievements, reactions).
 2. **Log** — what happened. Your hooks call `recordLog` / `recordMetricChange`. Grant and revoke write their own rows.
-3. **Grants** — what someone has earned. One row per user (+ scope). Creating or deleting a grant updates the log and re-checks composed achievements and ranks.
+3. **Grants** — what someone has earned. One row per user (+ scope). Creating or deleting a grant updates the log and re-checks composed achievements and tiers.
 4. **Reactions** — set-based side effects when a host event is logged or an achievement is granted/revoked.
 
 Writing a host or metric log also re-checks composed achievements and derived tiers. Grant and revoke logs skip that path because the Grants hooks already ran it.
@@ -81,7 +96,7 @@ Slugs use the prefix `achievement-` so they sit beside your own collections. Ove
 | `achievements` | `achievement-definitions` | Earnable items with eligibility and completion rules. |
 | `grants` | `achievement-grants` | One earned achievement per user (+ scope). |
 | `achievementRequests` | `achievement-requests` | Request → pending / approved / rejected. |
-| `tierRequests` | `achievement-tier-requests` | Rank unlock waiting on review (`requiresReview` on the tier). |
+| `tierRequests` | `achievement-tier-requests` | Tier unlock waiting on review (`requiresReview` on the tier). |
 | `logs` | `achievement-logs` | Activity history. |
 | `reactions` | `achievement-reactions` | Side effects when something is logged or granted. |
 
@@ -98,11 +113,11 @@ Flags on the type decide which log fields Admin asks for:
 | Requires an actor | `actor` — who caused it (a peer, an admin, …) |
 | Adjusts a metric | `metric` + `change` |
 | Requires a subject | `subject` — the host document (a post, a comment, a user, …) |
-| Snapshot actor tiers | stamps the actor’s derived rank at write time |
+| Snapshot actor tiers | stamps the actor’s derived tier at write time |
 
-**Actor tier** on an `event-count` rule then counts only logs whose snapshot already met that rank in this scope. Leave Actor tier blank to count every matching event. A filter only matches logs that were stamped.
+**Actor tier** on an `event-count` rule then counts only logs whose snapshot already met that tier in this scope. Leave Actor tier blank to count every matching event. A filter only matches logs that were stamped.
 
-Unscoped logs stamp every ladder. Scoped logs stamp that tenant plus any unscoped ranks.
+Unscoped logs stamp every ladder. Scoped logs stamp that tenant plus any unscoped tiers.
 
 ## Subjects
 
@@ -161,7 +176,7 @@ Unlock (tiers), eligibility, and completion (achievements) share one tree:
 
 **Eligibility** gates who may request an achievement. **Completion** describes what a composed achievement is made of. When `requiresReview` is off and completion passes, the parent grants itself. Nested achievement graphs skip cycles.
 
-**Current tier** walks ranks in order (`resolveCurrentTier`). A tier with `requiresReview` becomes current after an **approved** tier request. Turning `requiresReview` off approves pending requests for that row and writes missing `tier.changed` logs for people who already meet the unlock rules.
+**Current tier** walks the ladder in `rank` order (`resolveCurrentTier`). A tier with `requiresReview` becomes current after an **approved** tier request. Turning `requiresReview` off approves pending requests for that row and writes missing `tier.changed` logs for people who already meet the unlock rules.
 
 **Next-tier fill** (`resolveTierProgress` / `evaluateRuleProgress`):
 
@@ -380,7 +395,7 @@ achievementPlugin({
 | Option | Default | Notes |
 | --- | --- | --- |
 | `me` | `'/achievements/me'` | Signed-in user’s grants, derived tiers, lean requests. `?reviews=1` adds a review snapshot. Always the caller’s own snapshot. `false` skips it. |
-| `leaderboard` | `'/achievements/leaderboard'` | Stored-metric ranks. `false` skips it. |
+| `leaderboard` | `'/achievements/leaderboard'` | Stored-metric leaderboard. `false` skips it. |
 | `reconcile` | `'/achievements/reconcile'` | Reviewer repair endpoint. `false` skips it. |
 
 `me` query: `scope`, `limit`, `page`, `requestsLimit`, `reviews`. Leaderboard: `metric` (required), `scope`, `limit`, `page`.

package/dist/admin/LucideIconField.d.ts

@@ -1,6 +1,7 @@
-import type { TextFieldClientComponent } from 'payload';
+import type { TextFieldClientProps } from 'payload';
+import React from 'react';
 /**
  * Emoji-picker style Lucide field: searchable icon grid, stores kebab-case names.
  */
-export declare const LucideIconField: TextFieldClientComponent;
+export declare function LucideIconField(props: TextFieldClientProps): React.JSX.Element;
 //# sourceMappingURL=LucideIconField.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"LucideIconField.d.ts","sourceRoot":"","sources":["../../src/admin/LucideIconField.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,SAAS,CAAA;AAoCvD;;GAEG;AACH,eAAO,MAAM,eAAe,EAAE,wBAsO7B,CAAA"}
+{"version":3,"file":"LucideIconField.d.ts","sourceRoot":"","sources":["../../src/admin/LucideIconField.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAA;AAGnD,OAAO,KAA4D,MAAM,OAAO,CAAA;AAiChF;;GAEG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,oBAAoB,qBAsO1D"}

package/dist/admin/LucideIconField.js

@@ -28,7 +28,7 @@ const CELL = 36;
 /**
  * Emoji-picker style Lucide field: searchable icon grid, stores kebab-case names.
  */
-export const LucideIconField = (props) => {
+export function LucideIconField(props) {
     const { field, path: pathFromProps, readOnly } = props;
     const path = pathFromProps ?? field?.name ?? 'icon';
     const { errorMessage, setValue, showError, value } = useField({
@@ -168,4 +168,4 @@ export const LucideIconField = (props) => {
                                     : totalMatches > MAX_VISIBLE
                                         ? `Showing ${MAX_VISIBLE} of ${totalMatches} — refine search`
                                         : `${totalMatches} icon${totalMatches === 1 ? '' : 's'}` })] })) : null] }), _jsx(FieldDescription, { description: field?.admin?.description, path: path }), _jsx(FieldError, { message: errorMessage, path: path, showError: showError })] }));
-};
+}

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

@@ -1,12 +1,2 @@
-export declare const access: {
-    admin?: ({ req }: {
-        req: import("payload").PayloadRequest;
-    }) => boolean | Promise<boolean>;
-    create?: import("payload").Access;
-    delete?: import("payload").Access;
-    read?: import("payload").Access;
-    readVersions?: import("payload").Access;
-    unlock?: import("payload").Access;
-    update?: import("payload").Access;
-};
+export declare const access: import("payload").CollectionAccess<any>;
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/collections/EventTypes/access/index.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,MAAM;;;;;;;;;;CAAiC,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/collections/EventTypes/access/index.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,MAAM,yCAAiC,CAAA"}

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

@@ -1,12 +1,2 @@
-export declare const access: {
-    admin?: ({ req }: {
-        req: import("payload").PayloadRequest;
-    }) => boolean | Promise<boolean>;
-    create?: import("payload").Access;
-    delete?: import("payload").Access;
-    read?: import("payload").Access;
-    readVersions?: import("payload").Access;
-    unlock?: import("payload").Access;
-    update?: import("payload").Access;
-};
+export declare const access: import("payload").CollectionAccess<any>;
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/collections/Metrics/access/index.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,MAAM;;;;;;;;;;CAA8B,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/collections/Metrics/access/index.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,MAAM,yCAA8B,CAAA"}

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

@@ -1,12 +1,2 @@
-export declare const access: {
-    admin?: ({ req }: {
-        req: import("payload").PayloadRequest;
-    }) => boolean | Promise<boolean>;
-    create?: import("payload").Access;
-    delete?: import("payload").Access;
-    read?: import("payload").Access;
-    readVersions?: import("payload").Access;
-    unlock?: import("payload").Access;
-    update?: import("payload").Access;
-};
+export declare const access: import("payload").CollectionAccess<any>;
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/collections/Reactions/access/index.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,MAAM;;;;;;;;;;CAAgC,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/collections/Reactions/access/index.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,MAAM,yCAAgC,CAAA"}

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

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

package/dist/collections/index.js

@@ -22,8 +22,20 @@ const builders = {
     logs: buildLogsCollection,
     reactions: buildReactionsCollection,
 };
+/**
+ * Payload 4 enables versions + authorship by default. Achievement collections are
+ * high-churn catalogs and append-only logs — opt out so hosts do not grow `_versions`
+ * / authorship columns for every grant, request, and metric balance.
+ */
+function withPayload4Defaults(collection) {
+    return {
+        ...collection,
+        versions: collection.versions ?? false,
+        authorship: collection.authorship ?? false,
+    };
+}
 /** Build achievement collections after plugin options are stored. */
 export function buildAchievementCollections() {
     const overrides = getAchievementOptions().collections?.overrides;
-    return Object.keys(builders).map((key) => applyCollectionOverrides(builders[key](), overrides?.[key]));
+    return Object.keys(builders).map((key) => applyCollectionOverrides(withPayload4Defaults(builders[key]()), overrides?.[key]));
 }