From 7d2c123072828aff89e9c67c76aa81491daa0ede Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E2=9C=A8=20Audrey=20=E2=9C=A8?= <audrey@audreyality.com>
Date: Mon, 17 Mar 2025 10:57:27 -0400
Subject: [PATCH] improve type specificity and clarity

---
 libs/common/src/tools/achievements/achievement-manager.ts   | 4 +++-
 libs/common/src/tools/achievements/event-store.spec.ts      | 0
 .../src/tools/achievements/examples/example-validators.ts   | 2 +-
 libs/common/src/tools/achievements/types.ts                 | 6 +++---
 4 files changed, 7 insertions(+), 5 deletions(-)
 create mode 100644 libs/common/src/tools/achievements/event-store.spec.ts

diff --git a/libs/common/src/tools/achievements/achievement-manager.ts b/libs/common/src/tools/achievements/achievement-manager.ts
index 6da26650bdb..86d47fc3cc7 100644
--- a/libs/common/src/tools/achievements/achievement-manager.ts
+++ b/libs/common/src/tools/achievements/achievement-manager.ts
@@ -10,6 +10,8 @@ function active(
   status$: Observable<AchievementEvent[]>,
 ): OperatorFunction<AchievementValidator[], AchievementValidator[]> {
   return pipe(
+    // TODO: accept a configuration observable that completes without
+    //       emission when the user has opted out of achievements
     withLatestFrom(status$),
     map(([monitors, log]) => {
       // partition the log into progress and earned achievements
@@ -23,7 +25,7 @@ function active(
         // 🧠 the filters could be lifted into a function argument & delivered
         //    as a `Map<FilterType, (monitor) => bool>
 
-        if (m.trigger === "once") {
+        if (m.trigger === "until-earned") {
           // monitor disabled if already achieved
           return !earnedByName.has(m.achievement);
         }
diff --git a/libs/common/src/tools/achievements/event-store.spec.ts b/libs/common/src/tools/achievements/event-store.spec.ts
new file mode 100644
index 00000000000..e69de29bb2d
diff --git a/libs/common/src/tools/achievements/examples/example-validators.ts b/libs/common/src/tools/achievements/examples/example-validators.ts
index 14055937c03..6c34ff9fb96 100644
--- a/libs/common/src/tools/achievements/examples/example-validators.ts
+++ b/libs/common/src/tools/achievements/examples/example-validators.ts
@@ -16,7 +16,7 @@ const TotallyAttachedValidator = {
   description: "Attached a file to a send or item",
   metric: ItemCreatedProgress,
   validator: Type.HasTag,
-  trigger: "once",
+  trigger: "until-earned",
   hidden: false,
   filter(item) {
     return item.tags?.includes("with-attachment") ?? false;
diff --git a/libs/common/src/tools/achievements/types.ts b/libs/common/src/tools/achievements/types.ts
index 8bd2f9b3333..e48707ff9b9 100644
--- a/libs/common/src/tools/achievements/types.ts
+++ b/libs/common/src/tools/achievements/types.ts
@@ -38,7 +38,7 @@ export type Achievement = {
   validator: ValidatorId;
 
   // pre-filter that disables the rule if it's met
-  trigger: "once" | RequireAtLeastOne<{ low: number; high: number }>;
+  trigger: "until-earned" | RequireAtLeastOne<{ low: number; high: number }>;
 
   // whether or not the achievement is hidden until it is earned
   hidden: boolean;
@@ -47,10 +47,10 @@ export type Achievement = {
 // consumed by validator
 export type AchievementValidator = Achievement & {
   // when the watch triggers on incoming user events
-  filter: (item: EventFormat) => boolean;
+  filter: (item: UserActionEvent) => boolean;
 
   // observe data from the event stream and produces measurements
-  measure?: (item: EventFormat, metrics: Map<MetricId, number>) => AchievementProgressEvent[];
+  measure?: (item: UserActionEvent, metrics: Map<MetricId, number>) => AchievementProgressEvent[];
 
   // monitors achievement progress and emits earned achievements
   award?: (