Skip to content
ContractSpec
Start here

lib.gamification-spec

Portable cross-vertical gamification campaign contracts and validation.

domainslibraryv2.1.4experimentalservernode
@lssm-tech/lib.gamification-spec
bun add @lssm-tech/lib.gamification-spec
Package source ↗Manifest ↗

Manifest declarations describe the current workspace; they do not verify registry publication or runtime execution.

Package guide

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.

ts
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.

Relationships

THIS PACKAGElib.gamification-spec14 import paths

Arrows point from a package to its direct dependency. Counts are derived from captured workspace manifests.

2 declarations

Declared capabilities

Lib Gamification Spec

Portable cross-vertical gamification campaign contracts and validation.

Scripts

  • buildcontractspec-bun-build build
  • build:bundlecontractspec-bun-build transpile
  • build:typescontractspec-bun-build types
  • cleanrimraf dist .turbo
  • devcontractspec-bun-build dev
  • lintbun lint:fix
  • lint:checknode ../../../../scripts/biome.cjs check .
  • lint:fixnode ../../../../scripts/biome.cjs check --write .
  • prebuildcontractspec-bun-build prebuild
  • publish:pkgbun publish --tolerate-republish --ignore-scripts --verbose
  • testbun test
  • typechecktsgo --noEmit