✨ Add achievement engine: registry, evaluation, unlock-bubble backend (G2)

.env.example

@@ -152,6 +152,7 @@ HEALTHCHECKS_REPORTS_DIGEST_URL=
 HEALTHCHECKS_BACKUP_URL=
 HEALTHCHECKS_INACTIVE_ACCOUNTS_SCAN_URL=
 HEALTHCHECKS_GAMIFICATION_RECONCILE_URL=
+HEALTHCHECKS_GAMIFICATION_ACHIEVEMENTS_SWEEP_URL=
 HEALTHCHECKS_OFFSITE_BACKUP_URL=
 
 # --- Public hosting on a VPS (see README "Public hosting (VPS)") ---

apps/api/nest-cli.json

@@ -6,6 +6,7 @@
   "sourceRoot": "src",
   "compilerOptions": {
     "deleteOutDir": true,
+    "assets": ["package.json"],
     "plugins": ["@nestjs/swagger"],
     "manualRestart": false,
     "builder": "tsc",

apps/api/prisma/migrations/20260902181141_add_user_achievement/migration.sql

@@ -0,0 +1,16 @@
+-- CreateTable
+CREATE TABLE "UserAchievement" (
+    "id" TEXT NOT NULL,
+    "userId" TEXT NOT NULL,
+    "key" TEXT NOT NULL,
+    "unlockedAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "displayedAt" TIMESTAMP(3),
+
+    CONSTRAINT "UserAchievement_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateIndex
+CREATE UNIQUE INDEX "UserAchievement_userId_key_key" ON "UserAchievement"("userId", "key");
+
+-- AddForeignKey
+ALTER TABLE "UserAchievement" ADD CONSTRAINT "UserAchievement_userId_fkey" FOREIGN KEY ("userId") REFERENCES "User"("id") ON DELETE CASCADE ON UPDATE CASCADE;

apps/api/prisma/schema.prisma

@@ -575,6 +575,7 @@ model User {
   subscriptions              Subscription[]
   xpEntries                  XpEntry[]
   score                      UserScore?
+  achievements               UserAchievement[]
 
   @@index([lastActiveAt])
 }
@@ -1668,3 +1669,29 @@ model UserScore {
 
   @@index([xp])
 }
+
+// One row per unlocked achievement. Definitions live in code
+// (apps/api/src/gamification/achievements/registry.ts), never in the
+// database — a self-host install must never need seeding. Achievements are
+// never revoked once unlocked, unlike XpEntry: a trophy isn't taken back
+// because you later removed the title that earned it.
+model UserAchievement {
+  id     String @id @default(cuid())
+  userId String
+  // Stable key matching a registry entry — string, not a Prisma enum, so a
+  // new achievement needs no migration (same rationale as XpEntry.reason).
+  // Each tier of a tiered achievement is its own key (e.g.
+  // "cinephile_bronze"/"cinephile_silver"/"cinephile_gold"), not a shared
+  // row with a tier column.
+  key        String
+  unlockedAt DateTime  @default(now())
+  // Null until the [G6] unlock-bubble UI has shown this achievement to the
+  // user once — set by PATCH /achievements/:id/displayed. Independent of
+  // unlockedAt: an unlock can happen server-side (a live action, or the
+  // nightly sweep) while the user isn't even in the app.
+  displayedAt DateTime?
+
+  user User @relation(fields: [userId], references: [id], onDelete: Cascade)
+
+  @@unique([userId, key])
+}

apps/api/src/config/public-config.controller.ts

@@ -23,7 +23,7 @@ export class PublicConfigController {
   @Get()
   @ApiOkResponse({ type: PublicConfigResponseDto })
   async get(): Promise<PublicConfigDto> {
-    const raw = await readFile(join(process.cwd(), "package.json"), "utf-8");
+    const raw = await readFile(join(__dirname, "../../package.json"), "utf-8");
     const { version } = JSON.parse(raw) as { version: string };
 
     return {

apps/api/src/gamification/achievements/achievement.service.spec.ts

@@ -0,0 +1,250 @@
+import type { ConfigService } from "@nestjs/config";
+import { Prisma } from "@prisma/client";
+import { vi, type Mock } from "vitest";
+import type { FeatureFlagsService } from "../../feature-flags/feature-flags.service";
+import type { JobRunService } from "../../jobs/job-run.service";
+import type { PrismaService } from "../../prisma/prisma.service";
+import type { XpService } from "../xp.service";
+import { AchievementService } from "./achievement.service";
+
+// A socialGated achievement to exercise the [G3]-reserved gate — none of
+// this ticket's own registry entries (first_episode, cinephile_*) use it.
+const { socialGatedCheck } = vi.hoisted(() => ({
+  socialGatedCheck: vi.fn(),
+}));
+
+vi.mock("./registry", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("./registry")>();
+  const socialGatedDefinition = {
+    key: "test_social_gated",
+    xpAward: 10,
+    socialGated: true,
+    check: socialGatedCheck,
+  };
+  return {
+    ...actual,
+    ACHIEVEMENTS: {
+      ...actual.ACHIEVEMENTS,
+      test_social_gated: socialGatedDefinition,
+    },
+    ACHIEVEMENT_LIST: [...actual.ACHIEVEMENT_LIST, socialGatedDefinition],
+  };
+});
+
+function uniqueConstraintError(): Prisma.PrismaClientKnownRequestError {
+  return new Prisma.PrismaClientKnownRequestError("Unique constraint failed", {
+    code: "P2002",
+    clientVersion: "test",
+  });
+}
+
+function makeConfig(values: Record<string, string> = {}): ConfigService {
+  return {
+    get: vi.fn((key: string) => values[key]),
+  } as unknown as ConfigService;
+}
+
+// No Unleash client configured in tests — isEnabled always returns whatever
+// fallback the caller passed, same convention as xp.service.spec.ts.
+function makeFlags(): FeatureFlagsService {
+  return {
+    isEnabled: vi.fn((_name: string, fallback: boolean) => fallback),
+  } as unknown as FeatureFlagsService;
+}
+
+function makeService(configValues: Record<string, string> = {}) {
+  const prisma = {
+    userAchievement: {
+      findUnique: vi.fn().mockResolvedValue(null),
+      create: vi.fn().mockResolvedValue({ id: "achievement-1" }),
+      findMany: vi.fn().mockResolvedValue([]),
+      update: vi.fn().mockResolvedValue({}),
+    },
+    episodeWatch: { findFirst: vi.fn().mockResolvedValue(null) },
+    libraryEntry: { count: vi.fn().mockResolvedValue(0) },
+    xpEntry: { findMany: vi.fn().mockResolvedValue([]) },
+    user: { findMany: vi.fn().mockResolvedValue([]) },
+  } as unknown as PrismaService;
+  const config = makeConfig({ GAMIFICATION_ENABLED: "true", ...configValues });
+  const flags = makeFlags();
+  const xp = { award: vi.fn() } as unknown as XpService;
+  const jobRuns = {
+    record: vi.fn((_key: string, fn: () => Promise<unknown>) => fn()),
+  } as unknown as JobRunService;
+
+  const service = new AchievementService(prisma, config, flags, xp, jobRuns);
+  return { service, prisma, config, flags, xp, jobRuns };
+}
+
+describe("AchievementService.evaluate", () => {
+  it("unlocks a satisfied achievement, credits its xpAward via amountOverride, sourced from the created row's id", async () => {
+    const { service, prisma, xp } = makeService();
+    (prisma.episodeWatch.findFirst as Mock).mockResolvedValue({ id: "w1" });
+
+    await service.evaluate("user-1", ["first_episode"]);
+
+    expect(prisma.userAchievement.create).toHaveBeenCalledWith({
+      data: { userId: "user-1", key: "first_episode" },
+    });
+    expect(xp.award).toHaveBeenCalledWith(
+      "user-1",
+      "ACHIEVEMENT_UNLOCKED",
+      "achievement-1",
+      50,
+    );
+  });
+
+  it("does not even call check() when the achievement is already unlocked", async () => {
+    const { service, prisma } = makeService();
+    (prisma.userAchievement.findUnique as Mock).mockResolvedValue({
+      id: "achievement-1",
+    });
+
+    await service.evaluate("user-1", ["first_episode"]);
+
+    expect(prisma.episodeWatch.findFirst).not.toHaveBeenCalled();
+    expect(prisma.userAchievement.create).not.toHaveBeenCalled();
+  });
+
+  it("stays locked when the check reports unlocked: false", async () => {
+    const { service, prisma, xp } = makeService();
+    (prisma.episodeWatch.findFirst as Mock).mockResolvedValue(null);
+
+    await service.evaluate("user-1", ["first_episode"]);
+
+    expect(prisma.userAchievement.create).not.toHaveBeenCalled();
+    expect(xp.award).not.toHaveBeenCalled();
+  });
+
+  it("no-ops entirely (no read, no write) when GAMIFICATION_ENABLED is off", async () => {
+    const { service, prisma } = makeService({ GAMIFICATION_ENABLED: "false" });
+
+    await service.evaluate("user-1");
+
+    expect(prisma.userAchievement.findUnique).not.toHaveBeenCalled();
+  });
+
+  it("never unlocks a socialGated achievement while SOCIAL_ENABLED is off", async () => {
+    const { service, prisma, xp } = makeService();
+    socialGatedCheck.mockResolvedValue({ unlocked: true });
+
+    await service.evaluate("user-1", ["test_social_gated"]);
+
+    expect(socialGatedCheck).not.toHaveBeenCalled();
+    expect(prisma.userAchievement.create).not.toHaveBeenCalled();
+    expect(xp.award).not.toHaveBeenCalled();
+  });
+
+  it("credits no XP when create() hits the unique constraint (concurrent unlock)", async () => {
+    const { service, prisma, xp } = makeService();
+    (prisma.episodeWatch.findFirst as Mock).mockResolvedValue({ id: "w1" });
+    (prisma.userAchievement.create as Mock).mockRejectedValue(
+      uniqueConstraintError(),
+    );
+
+    await expect(
+      service.evaluate("user-1", ["first_episode"]),
+    ).resolves.toBeUndefined();
+    expect(xp.award).not.toHaveBeenCalled();
+  });
+
+  it("evaluates only the registry entries named by `keys`", async () => {
+    const { service, prisma } = makeService();
+
+    await service.evaluate("user-1", ["first_episode"]);
+
+    // Only first_episode's own uniqueness check runs — cinephile's tiers
+    // and the socialGated test fixture are skipped entirely.
+    expect(prisma.userAchievement.findUnique).toHaveBeenCalledTimes(1);
+    expect(prisma.userAchievement.findUnique).toHaveBeenCalledWith({
+      where: { userId_key: { userId: "user-1", key: "first_episode" } },
+      select: { id: true },
+    });
+  });
+});
+
+describe("AchievementService.pending", () => {
+  it("returns unlocked-but-undisplayed achievements, oldest first, with xpAwarded looked up from the matching XpEntry", async () => {
+    const { service, prisma } = makeService();
+    (prisma.userAchievement.findMany as Mock).mockResolvedValue([
+      {
+        id: "achievement-1",
+        key: "first_episode",
+        unlockedAt: new Date("2026-01-01T00:00:00.000Z"),
+      },
+    ]);
+    (prisma.xpEntry.findMany as Mock).mockResolvedValue([
+      { sourceId: "achievement-1", amount: 50 },
+    ]);
+
+    await expect(service.pending("user-1")).resolves.toEqual([
+      {
+        id: "achievement-1",
+        key: "first_episode",
+        unlockedAt: "2026-01-01T00:00:00.000Z",
+        xpAwarded: 50,
+      },
+    ]);
+    expect(prisma.userAchievement.findMany).toHaveBeenCalledWith({
+      where: { userId: "user-1", displayedAt: null },
+      orderBy: { unlockedAt: "asc" },
+    });
+  });
+
+  it("returns an empty list (not an error) when GAMIFICATION_ENABLED is off", async () => {
+    const { service, prisma } = makeService({ GAMIFICATION_ENABLED: "false" });
+
+    await expect(service.pending("user-1")).resolves.toEqual([]);
+    expect(prisma.userAchievement.findMany).not.toHaveBeenCalled();
+  });
+});
+
+describe("AchievementService.markDisplayed", () => {
+  it("404s on an achievement belonging to another user", async () => {
+    const { service, prisma } = makeService();
+    (prisma.userAchievement.findUnique as Mock).mockResolvedValue({
+      userId: "someone-else",
+      displayedAt: null,
+    });
+
+    await expect(
+      service.markDisplayed("user-1", "achievement-1"),
+    ).rejects.toThrow();
+    expect(prisma.userAchievement.update).not.toHaveBeenCalled();
+  });
+
+  it("404s on an unknown id", async () => {
+    const { service, prisma } = makeService();
+    (prisma.userAchievement.findUnique as Mock).mockResolvedValue(null);
+
+    await expect(service.markDisplayed("user-1", "missing")).rejects.toThrow();
+  });
+
+  it("sets displayedAt on first call", async () => {
+    const { service, prisma } = makeService();
+    (prisma.userAchievement.findUnique as Mock).mockResolvedValue({
+      userId: "user-1",
+      displayedAt: null,
+    });
+
+    await service.markDisplayed("user-1", "achievement-1");
+
+    expect(prisma.userAchievement.update).toHaveBeenCalledWith({
+      where: { id: "achievement-1" },
+      data: { displayedAt: expect.any(Date) },
+    });
+  });
+
+  it("is idempotent: a second call is a no-op, not an error", async () => {
+    const { service, prisma } = makeService();
+    (prisma.userAchievement.findUnique as Mock).mockResolvedValue({
+      userId: "user-1",
+      displayedAt: new Date("2026-01-01T00:00:00.000Z"),
+    });
+
+    await expect(
+      service.markDisplayed("user-1", "achievement-1"),
+    ).resolves.toBeUndefined();
+    expect(prisma.userAchievement.update).not.toHaveBeenCalled();
+  });
+});