@bayonai/gamify

Storage-agnostic progress, goals, ranks, and contextual-guidance rule primitives for Bayonai applications.

The package owns reusable game mechanics. Each host application owns its event catalog, user-facing labels, persistence adapter, and the places where events are recorded. Thunderlist can count task.created; Bounded can define entirely different counters without changing this package.

Install

pnpm add @bayonai/gamify

Record progress

import { createGameProgress, getCounter, recordAction } from "@bayonai/gamify";

type AppCounter = "search.used" | "task.created";

const initial = createGameProgress<AppCounter>();
const updated = recordAction(initial, "task.created");

getCounter(updated, "task.created"); // 1

All updates are immutable. Persistence adapters can write the returned version and counters fields alongside their own timestamps.

Goals and ranks

import { evaluateGoal, resolveRank } from "@bayonai/gamify";

const goal = evaluateGoal(updated, {
  counter: "task.created",
  id: "first-five-tasks",
  target: 5,
});

const rank = resolveRank(1, [
  { minimumActions: 0, rank: "Noob" },
  { minimumActions: 10, rank: "Regular" },
]);

Ranks are derived display values. They are not stored in GameProgress.

Contextual guidance rules

Host applications can choose one eligible, incomplete guidance rule for a specific surface. The package only resolves priority and goal completion; the host application supplies the copy and UI.

import { resolveNextTutorial } from "@bayonai/gamify";

const next = resolveNextTutorial(
  updated,
  [
    {
      goal: { counter: "task.created", id: "create-first-tasks", target: 3 },
      id: "task-capture",
      isEligible: (surface: "task-capture" | "search") =>
        surface === "task-capture",
      priority: 1,
    },
  ],
  "task-capture" as const,
);

next contains the selected rule and its derived goal progress, or null when no rule is eligible. A guidance rule can carry host-defined extra fields, such as a message factory, placement, or icon choice.

API

• createGameProgress, parseGameProgress, recordAction, getCounter, and getTotalActions manage validated, immutable counter snapshots.
• evaluateGoal calculates current, remaining, ratio, and completion state.
• resolveRank derives a display label from application-owned thresholds.
• resolveNextTutorial selects the next eligible incomplete guidance rule by ascending priority, then stable rule ID.

The package supports Node.js 20.11+ and publishes typed ESM and CommonJS root entrypoints.

Package boundary

@bayonai/gamify intentionally does not include:

• Product-specific counter IDs, labels, thresholds, or rewards.
• Firebase, Firestore, authentication, or database paths.
• UI-library components or application navigation.
• Analytics transport or an event log.

Those concerns stay in each application through a small adapter and catalog.

Commercial use

This package is publicly distributed under an UNLICENSED proprietary model. Downloading it grants no permission to use, copy, modify, or distribute it. Commercial rights require a separate agreement with the package owner.

Release verification

Maintainers can run the artifact check without publishing:

pnpm --dir packages/bayonai-gamify run release:check

See PUBLISHING.md for release prerequisites and the manual publication procedure. The final publish:check enforces the intentional public-but-proprietary UNLICENSED distribution policy.