lib.gamification-spec

@lssm-tech/lib.gamification-spec

Portable contracts for building gamified experiences in any ContractSpec vertical. The package describes campaigns, cadence slots, outcomes, streaks, quests, badges, XP, leaderboards, leagues, social play, and reward inventories.

It contains no persistence, network calls, provider adapters, UI, user discovery, or notification delivery. Use @lssm-tech/lib.gamification-runtime for pure, deterministic evaluation and replay.

import { defineGamificationCampaign } from "@lssm-tech/lib.gamification-spec";

const campaign = defineGamificationCampaign({
  id: "finance-reset",
  version: "1.0.0",
  name: "Finance reset",
  missions: [{
    id: "daily-review",
    cadence: { kind: "daily", timezone: "Europe/Paris", startDate: "2026-01-01" },
    completion: { kind: "event", eventName: "finance.review.completed" },
    xpRuleId: "daily-review-xp",
  }],
  xpRules: [{ id: "daily-review-xp", source: "daily-review", base: 10 }],
});

Grouped public subpaths are available for ./campaign, ./cadence, ./conditions, ./scoring, ./social, ./economy, ./events, ./validation, ./fixtures, ./types, and ./docs.

Campaign validation rejects empty or duplicate public IDs, invalid IANA timezones and calendar dates, offset-aware overlapping explicit slots, invalid XP rules/caps/modifiers, condition cycles and malformed primitives, malformed badge tiers, records, rewards and league bounds, undeclared wallet assets, and unsupported policy references. The contracts remain plain JSON data; the host supplies participant authorization, evidence references, persistence, and delivery infrastructure.

The optional posting-streak surface projects unique calendar posting days with an explicit IANA timezone and clock. Yesterday retains the active streak until the current day ends; future posts do not count. The projection is read-only and awards no XP or compensation. It includes a Sunday–Saturday strip with active-streak day numbering.