@takaro/module-test 0.0.0-dev.2f94734

package/README.md

@@ -0,0 +1,260 @@
+# @takaro/module-test
+
+Unit-test your Takaro module's logic without a Takaro server. The harness runs your command, hook,
+cron job and shop action code in the real module VM (`executeVM` from `@takaro/helpers`), against a
+typed in-memory fake of the `@takaro/apiclient` `Client`. No database, no queue, no game server and
+no HTTP.
+
+## Install
+
+```sh
+npm i -D @takaro/module-test
+```
+
+Pick the version that matches the Takaro version you target. The package is released in lockstep
+with Takaro and depends on the exact `@takaro/apiclient` and `@takaro/helpers` versions it fakes.
+
+It needs Node 24 or newer.
+
+## A minimal standalone repo
+
+```
+my-module/
+  package.json
+  module.json
+  src/commands/greet.js
+  test/greet.test.ts
+```
+
+`package.json`:
+
+```json
+{
+  "name": "my-module",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "test": "node --experimental-vm-modules --test 'test/**/*.test.ts'"
+  },
+  "devDependencies": {
+    "@takaro/module-test": "<the version you target>"
+  }
+}
+```
+
+`module.json` describes the module and points each component at a JavaScript file:
+
+```json
+{
+  "name": "my-module",
+  "version": "1.0.0",
+  "description": "Greets players",
+  "config": {
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "type": "object",
+    "properties": {
+      "greeting": { "type": "string", "default": "Hello" }
+    },
+    "required": [],
+    "additionalProperties": false
+  },
+  "commands": {
+    "greet": {
+      "function": "src/commands/greet.js",
+      "helpText": "Greet a player",
+      "arguments": [{ "name": "target", "type": "string", "defaultValue": "world", "position": 0 }]
+    }
+  }
+}
+```
+
+`src/commands/greet.js`:
+
+```js
+import { takaro, data } from '@takaro/helpers';
+
+const { greeting } = data.module.userConfig;
+const { target } = data.arguments;
+
+await data.player.pm(`${greeting}, ${target}!`);
+await takaro.variable.variableControllerCreate({ key: 'lastGreeted', value: target, playerId: data.player.id });
+```
+
+## A complete test
+
+`test/greet.test.ts`:
+
+```ts
+import assert from 'node:assert/strict';
+import { describe } from 'node:test';
+import { createModuleTest } from '@takaro/module-test';
+
+describe('greet', () => {
+  createModuleTest({
+    name: 'greets the default target',
+    module: new URL('..', import.meta.url),
+    test: async function () {
+      const result = await this.runCommand('greet');
+
+      assert.equal(result.success, true, JSON.stringify(result.logs));
+      assert.deepEqual(this.pms(), ['Hello, world!']);
+      assert.deepEqual(
+        this.variables.all.map((row) => [row.key, row.value]),
+        [['lastGreeted', 'world']],
+      );
+    },
+  }).run();
+
+  createModuleTest({
+    name: 'greets a named target with a custom greeting',
+    module: new URL('..', import.meta.url),
+    userConfig: { greeting: 'Howdy' },
+    test: async function () {
+      await this.runCommand('greet', { target: 'partner' });
+
+      assert.deepEqual(this.pms(), ['Howdy, partner!']);
+    },
+  }).run();
+});
+```
+
+Run it:
+
+```sh
+npm test
+```
+
+**`--experimental-vm-modules` is required.** The module VM is built on `vm.SourceTextModule`, which
+Node only exposes behind that flag. Without it the test fails with a message saying so. Node 24
+strips TypeScript types natively; a `.js` test works the same way.
+
+`module` takes one of:
+
+- a **directory** in the registry source layout: a path (relative paths resolve against
+  `process.cwd()`) or a `file:` URL. `new URL('..', import.meta.url)` is the robust choice.
+  `loadModuleDirectory(dir)` is exported if you want the loaded object itself.
+- a **module export object**: Takaro's module export format, the same shape as a registry's
+  `<module>/<version>.json`. Parse a published version file or an export downloaded from Takaro and
+  pass it in.
+
+```ts
+import { readFileSync } from 'node:fs';
+import { createModuleTest } from '@takaro/module-test';
+
+const exported = JSON.parse(readFileSync('dist/my-module/1.0.0.json', 'utf8'));
+createModuleTest({ name: 'from an export', module: exported, test: async function () {} }).run();
+```
+
+A directory yields one version. An export object may carry several: the last is installed unless
+`versionTag` picks another.
+
+## Using another test runner
+
+`run()` registers the test with `node:test`. For another runner, register it yourself:
+
+```ts
+import { it } from 'vitest';
+
+const t = createModuleTest({ name: 'greets', module: new URL('..', import.meta.url), test: async function () {} });
+it(t.spec.name, t.testOptions(), () => t.runBody());
+```
+
+`testOptions()` is `{ timeout?, skip? }` derived from the spec; `runBody()` builds the fixtures, runs
+`setup`, then `test`. The runner must still be started with `--experimental-vm-modules`.
+
+## Spec options
+
+`name`, `module` and `test` are required.
+
+| Option          | Type                                                            | What it does                                                                                                                                                                                                             |
+| --------------- | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `name`          | `string`                                                        | The test name.                                                                                                                                                                                                           |
+| `module`        | `string \| URL \| ModuleExport`                                 | The module under test: a directory or an export object.                                                                                                                                                                  |
+| `versionTag`    | `string`                                                        | Install this version instead of the last one.                                                                                                                                                                            |
+| `userConfig`    | `Record<string, unknown>`                                       | Overrides on the module's own config schema. Unset fields get **real** ajv defaults, and the result is validated.                                                                                                        |
+| `systemConfig`  | `{ enabled?, commands?: { [name]: { enabled?, cost?, ... } } }` | Overrides on the derived system config schema (commands, hooks, cron jobs, shop actions). Unset fields get Takaro's own ajv defaults.                                                                                    |
+| `alsoInstalled` | `Array<{ module, userConfig?, systemConfig? }>`                 | Further modules installed on the same game server, for module code that enumerates installations.                                                                                                                        |
+| `permissions`   | `'ROOT'` \| `Array<{ permission, count?, module? }>`            | The acting player's permissions. Defaults to `'ROOT'`; read the `checkPermission` note below. A grant belongs to the module under test unless `module` names another installed module; only that module's checks see it. |
+| `player`        | `PlayerSpec`                                                    | The rest of the acting player's fixture: `name`, `gameId`, `playerId`, `ping`, `ip`, `online`, `position`, `steamId` and the other platform ids.                                                                         |
+| `user`          | `{ userId? }`                                                   | Links the acting player to a Takaro user, putting `user` on command payloads. **Omitted means unlinked**, which is Takaro's default. Pass `{}` to link.                                                                  |
+| `otherPlayers`  | `PlayerSpec[]`                                                  | Further players on the same game server, reachable as `this.otherPlayers`.                                                                                                                                               |
+| `settings`      | `Record<string, string>`                                        | Domain settings. `commandPrefix`, `serverChatName` and `currencyName` have defaults; anything else throws `MissingFixtureError` until you set it.                                                                        |
+| `variables`     | `VariableSeed[]`                                                | Rows seeded into the variable store: `{ key, value, expiresAt?, gameServerId?, playerId?, moduleId? }`. An omitted scope column is NULL.                                                                                 |
+| `currency`      | `number`                                                        | The acting player's starting balance.                                                                                                                                                                                    |
+| `now`           | `Date`                                                          | Freezes the VM's clock, and the store's TTL comparisons with it.                                                                                                                                                         |
+| `random`        | `number \| number[]`                                            | Scripts `Math.random()` inside the VM. An array is consumed in order; the last value repeats once exhausted.                                                                                                             |
+| `timeout`       | `number`                                                        | Passed to the test runner.                                                                                                                                                                                               |
+| `quarantine`    | `string`                                                        | Skip the test with this reason.                                                                                                                                                                                          |
+| `setup`         | `(this: ModuleTest) => void \| Promise<void>`                   | Runs after the fixtures are built and before `test`. Stub extra client methods here.                                                                                                                                     |
+| `test`          | `(this: ModuleTest) => Promise<void>`                           | The test body.                                                                                                                                                                                                           |
+
+## Inside `setup` and `test`
+
+`this` is the `ModuleTest`:
+
+| Member                                                                    | What it gives you                                                                                           |
+| ------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
+| `runCommand(name, args?, opts?)`                                          | Executes a command's function and returns a `VMExecutionResult`. `opts.chatMessage` sets the raw chat line. |
+| `runHook(name, opts?)` / `runCronJob(name)` / `runShopAction(name, opts)` | The other three trigger kinds.                                                                              |
+| `pms()`                                                                   | `string[]`: messages sent privately to the acting player, in order.                                         |
+| `messages`                                                                | Every `gameServerControllerSendMessage` call, private or broadcast.                                         |
+| `client.pmsTo(gameId)`                                                    | `pms()` for any other player; pass `this.otherPlayers[n].pog.gameId`.                                       |
+| `variables`                                                               | The in-memory variable store. `variables.all` is every row, for assertions.                                 |
+| `currency`                                                                | The in-memory ledger. `currency.balanceOf(playerId)`.                                                       |
+| `client.stubs`                                                            | The sinon stubs, typed against the generated `Client`, keyed by controller then method.                     |
+| `userError(result)`                                                       | The `TakaroUserError` message a failed run produced.                                                        |
+| `player` / `pog`                                                          | The acting player's fixtures.                                                                               |
+| `user`                                                                    | The linked Takaro user fixture, or `undefined` when the spec declared no `user`.                            |
+| `otherPlayers`                                                            | `Array<{ player, pog }>` for the `otherPlayers` specs, in order.                                            |
+| `gameServerId` / `moduleId` / `installation`                              | The ids module code saw.                                                                                    |
+
+## Things that will catch you out
+
+- **The VM has its own `Date` and `Math`.** Host fake timers and stubs on `Math.random` do not reach
+  module code. Pass `now:` and `random:` on the test instead.
+- **`--experimental-vm-modules` is required**, see above.
+- **Type-checking with `tsc` needs `skipLibCheck: true`.** The typings of `sinon`, which the harness
+  depends on, do not check cleanly on their own. Tests run under Node's type stripping need nothing.
+- **`data` is a JSON snapshot.** Each payload goes through a JSON round-trip, as it does in Takaro,
+  so `data.pog.currency` is the balance at trigger time and a `Date` arrives as a string. Assert on
+  `this.currency`, `this.variables` or `this.pog` for the state after the run.
+- **User errors come through `userError(result)`.** `executeVM` returns `{ success: false, logs }`;
+  delivering a `TakaroUserError` to the player happens outside the VM and is not covered.
+- **Command cost is not modelled.** Takaro charges it around the VM call, so module code never sees it.
+- **Config defaults are real.** `userConfig` and `systemConfig` are filled and validated with ajv. A
+  config Takaro would reject throws `InvalidUserConfigError` or `InvalidSystemConfigError`, and a
+  module whose schema has a required field with no default cannot be installed without it. A
+  `discord-message` hook requires `discordChannelId` in `systemConfig.hooks.<name>`.
+- **`checkPermission` returns the boolean `true` for ROOT**, so `.count` is `undefined`. ROOT is the
+  default, which makes a count-limited test unable to fail; use
+  `permissions: [{ permission: 'MY_PERMISSION', count: 3 }]` when the count is the subject.
+- **Arguments get defaults, not parsing.** The harness applies `defaultValue` from your command's
+  arguments. Tokenising a chat line belongs to Takaro; pass already-tokenised values.
+- **The fake refuses what it cannot answer faithfully.** `UnstubbedMethodError` means module code
+  called an API method the fake does not cover. `MissingFixtureError` means a covered method has
+  nothing in this test to answer with; its message names the spec option to set.
+  `UnsupportedQueryError` means a query used a filter, sort or option the fake cannot honour.
+  Stub the method yourself instead.
+
+### Stubbing a method the fake refuses
+
+A stub replaces the whole response, so it must produce the axios envelope module code reads.
+`ok`, `single` and `paginated` build it. Every method on `client.stubs` is optional, so `?.` is
+required:
+
+```ts
+import { createModuleTest, paginated } from '@takaro/module-test';
+
+createModuleTest({
+  name: 'counts kills',
+  module: new URL('..', import.meta.url),
+  setup: function () {
+    this.client.stubs.event.eventControllerSearch?.callsFake(async () =>
+      paginated([{ id: 'e1', eventName: 'entity-killed', meta: { entity: 'zombie' } }]),
+    );
+  },
+  test: async function () {
+    // ...
+  },
+}).run();
+```

package/dist/.source-hash

@@ -0,0 +1 @@
+53e2b3f37588409c5957f389ab24219229d29d833d7c6d680b0752f858c1f566

package/dist/config.d.ts

@@ -0,0 +1,49 @@
+import type { ModuleExportVersion } from './moduleExport.js';
+export declare class InvalidUserConfigError extends Error {
+    constructor(moduleVersion: string, errors: string);
+}
+/** @internal Exported for tests only. */
+export declare function resolveUserConfig(version: ModuleExportVersion, overrides?: Record<string, unknown>): Record<string, unknown>;
+export interface SystemConfigOverrides {
+    enabled?: boolean;
+    commands?: Record<string, Partial<CommandSystemConfig>>;
+    hooks?: Record<string, Partial<HookSystemConfig>>;
+    cronJobs?: Record<string, Partial<CronJobSystemConfig>>;
+    shopActions?: Record<string, Partial<ShopActionSystemConfig>>;
+}
+export interface CommandSystemConfig {
+    enabled: boolean;
+    delay: number;
+    announceDelay: boolean;
+    cooldown: number;
+    cost: number;
+    aliases?: string[];
+}
+export interface HookSystemConfig {
+    enabled: boolean;
+    delay: number;
+    cooldown: number;
+    cooldownType: 'player' | 'server' | 'global';
+    discordChannelId?: string;
+}
+export interface CronJobSystemConfig {
+    enabled: boolean;
+    temporalValue: string;
+}
+export interface ShopActionSystemConfig {
+    enabled: boolean;
+    triggerOn: 'orderCreated' | 'orderClaimed' | 'both';
+}
+export interface SystemConfig {
+    enabled: boolean;
+    commands?: Record<string, CommandSystemConfig>;
+    hooks?: Record<string, HookSystemConfig>;
+    cronJobs?: Record<string, CronJobSystemConfig>;
+    shopActions?: Record<string, ShopActionSystemConfig>;
+}
+export declare class InvalidSystemConfigError extends Error {
+    constructor(moduleVersion: string, errors: string);
+}
+/** @internal Exported for tests only. */
+export declare function resolveSystemConfig(version: ModuleExportVersion, overrides?: SystemConfigOverrides): SystemConfig;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAS7D,qBAAa,sBAAuB,SAAQ,KAAK;IAC/C,YAAY,aAAa,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAMhD;CACF;AAED,yCAAyC;AACzC,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,mBAAmB,EAC5B,SAAS,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GACtC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAazB;AAED,MAAM,WAAW,qBAAqB;IACpC,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,mBAAmB,CAAC,CAAC,CAAC;IACxD,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,gBAAgB,CAAC,CAAC,CAAC;IAClD,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,mBAAmB,CAAC,CAAC,CAAC;IACxD,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,sBAAsB,CAAC,CAAC,CAAC;CAC/D;AAED,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,aAAa,EAAE,OAAO,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,QAAQ,GAAG,QAAQ,GAAG,QAAQ,CAAC;IAG7C,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,OAAO,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,EAAE,cAAc,GAAG,cAAc,GAAG,MAAM,CAAC;CACrD;AAED,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC;IAC/C,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;IACzC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC;IAC/C,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,sBAAsB,CAAC,CAAC;CACtD;AAGD,qBAAa,wBAAyB,SAAQ,KAAK;IACjD,YAAY,aAAa,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAMhD;CACF;AAID,yCAAyC;AACzC,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,mBAAmB,EAAE,SAAS,GAAE,qBAA0B,GAAG,YAAY,CAcrH"}

package/dist/config.js

@@ -0,0 +1,54 @@
+import Ajv from 'ajv';
+import { getSystemConfigSchema } from './systemConfig.js';
+// Same ajv config `ModuleService.installModule` compiles with, so a default asserted here is a
+// default a real install would carry.
+const ajv = new Ajv.default({ useDefaults: true, strict: false, allErrors: true });
+// A `userConfig` Takaro would have refused to install — guards against a rejected override
+// (e.g. a misspelled field) silently passing, so its author believes it applied.
+export class InvalidUserConfigError extends Error {
+    constructor(moduleVersion, errors) {
+        super(`userConfig is invalid against the module's own configSchema (version ${moduleVersion}): ${errors}. ` +
+            'Takaro validates the same schema with the same library, so this installation could not exist.');
+        this.name = 'InvalidUserConfigError';
+    }
+}
+/** @internal Exported for tests only. */
+export function resolveUserConfig(version, overrides = {}) {
+    // JSON, not structuredClone: the real override crosses a JSON boundary, which drops `undefined`.
+    const config = JSON.parse(JSON.stringify(overrides));
+    // ajv fills defaults (mutating) before it checks `required`, so this call completes and judges.
+    const validate = ajv.compile(JSON.parse(version.configSchema));
+    if (!validate(config)) {
+        // `params` (not just `errorsText`) carries the offending property name for `additionalProperties`.
+        const errors = (validate.errors ?? [])
+            .map((error) => `${error.instancePath || 'userConfig'} ${error.message} ${JSON.stringify(error.params)}`)
+            .join('; ');
+        throw new InvalidUserConfigError(version.tag, errors);
+    }
+    return config;
+}
+// The systemConfig counterpart of `InvalidUserConfigError`, same reason.
+export class InvalidSystemConfigError extends Error {
+    constructor(moduleVersion, errors) {
+        super(`systemConfig is invalid against the module's derived systemConfigSchema (version ${moduleVersion}): ${errors}. ` +
+            'Takaro validates the same schema with the same library, so this installation could not exist.');
+        this.name = 'InvalidSystemConfigError';
+    }
+}
+// Reproduces `ModuleService.installModule`. The shallow merge over `defaultSystemConfig` is
+// production's: a `commands` override replaces that block wholesale, not merges into it.
+/** @internal Exported for tests only. */
+export function resolveSystemConfig(version, overrides = {}) {
+    const declaredDefaults = JSON.parse(version.defaultSystemConfig ?? '{}');
+    // Same JSON round-trip as `resolveUserConfig`, same reason.
+    const config = { ...declaredDefaults, ...JSON.parse(JSON.stringify(overrides)) };
+    const validate = ajv.compile(JSON.parse(getSystemConfigSchema(version)));
+    if (!validate(config)) {
+        const errors = (validate.errors ?? [])
+            .map((error) => `${error.instancePath || 'systemConfig'} ${error.message} ${JSON.stringify(error.params)}`)
+            .join('; ');
+        throw new InvalidSystemConfigError(version.tag, errors);
+    }
+    return config;
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}

package/dist/currencyLedger.d.ts

@@ -0,0 +1,13 @@
+export declare class InsufficientFundsError extends Error {
+    readonly status = 400;
+    constructor(playerId: string, requested: number, balance: number);
+}
+export declare class CurrencyLedger {
+    private balances;
+    constructor(seed?: Record<string, number>);
+    balanceOf(playerId: string): number;
+    add(playerId: string, amount: number): number;
+    deduct(playerId: string, amount: number): number;
+    transact(senderId: string, receiverId: string, amount: number): void;
+}
+//# sourceMappingURL=currencyLedger.d.ts.map

package/dist/currencyLedger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"currencyLedger.d.ts","sourceRoot":"","sources":["../src/currencyLedger.ts"],"names":[],"mappings":"AAEA,qBAAa,sBAAuB,SAAQ,KAAK;IAC/C,QAAQ,CAAC,MAAM,OAAO;IACtB,YAAY,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAG/D;CACF;AAED,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAA6B;IAE7C,YAAY,IAAI,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAM,EAI5C;IAED,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAElC;IAED,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAI5C;IAED,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAQ/C;IAED,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAGnE;CACF"}

package/dist/currencyLedger.js

@@ -0,0 +1,39 @@
+// Deliberately does NOT model command cost: that's deducted around the VM call in
+// `executeFunction.ts`, and `lottery/commands/buyTicket.js` already compensates for it.
+export class InsufficientFundsError extends Error {
+    constructor(playerId, requested, balance) {
+        super(`Request failed with status code 400 (player ${playerId} has ${balance}, needs ${requested})`);
+        this.status = 400;
+        this.name = 'InsufficientFundsError';
+    }
+}
+export class CurrencyLedger {
+    constructor(seed = {}) {
+        this.balances = new Map();
+        for (const [playerId, amount] of Object.entries(seed)) {
+            this.balances.set(playerId, amount);
+        }
+    }
+    balanceOf(playerId) {
+        return this.balances.get(playerId) ?? 0;
+    }
+    add(playerId, amount) {
+        const next = this.balanceOf(playerId) + amount;
+        this.balances.set(playerId, next);
+        return next;
+    }
+    deduct(playerId, amount) {
+        const balance = this.balanceOf(playerId);
+        if (balance < amount) {
+            throw new InsufficientFundsError(playerId, amount, balance);
+        }
+        const next = balance - amount;
+        this.balances.set(playerId, next);
+        return next;
+    }
+    transact(senderId, receiverId, amount) {
+        this.deduct(senderId, amount);
+        this.add(receiverId, amount);
+    }
+}
+//# sourceMappingURL=currencyLedger.js.map

package/dist/currencyLedger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"currencyLedger.js","sourceRoot":"","sources":["../src/currencyLedger.ts"],"names":[],"mappings":"AAAA,kFAAkF;AAClF,wFAAwF;AACxF,MAAM,OAAO,sBAAuB,SAAQ,KAAK;IAE/C,YAAY,QAAgB,EAAE,SAAiB,EAAE,OAAe;QAC9D,KAAK,CAAC,+CAA+C,QAAQ,QAAQ,OAAO,WAAW,SAAS,GAAG,CAAC,CAAC;QAF9F,WAAM,GAAG,GAAG,CAAC;QAGpB,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAC;IACvC,CAAC;CACF;AAED,MAAM,OAAO,cAAc;IAGzB,YAAY,IAAI,GAA2B,EAAE;QAFrC,aAAQ,GAAG,IAAI,GAAG,EAAkB,CAAC;QAG3C,KAAK,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;YACtD,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;QACtC,CAAC;IACH,CAAC;IAED,SAAS,CAAC,QAAgB;QACxB,OAAO,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;IAC1C,CAAC;IAED,GAAG,CAAC,QAAgB,EAAE,MAAc;QAClC,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,GAAG,MAAM,CAAC;QAC/C,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;QAClC,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM,CAAC,QAAgB,EAAE,MAAc;QACrC,MAAM,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;QACzC,IAAI,OAAO,GAAG,MAAM,EAAE,CAAC;YACrB,MAAM,IAAI,sBAAsB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;QAC9D,CAAC;QACD,MAAM,IAAI,GAAG,OAAO,GAAG,MAAM,CAAC;QAC9B,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;QAClC,OAAO,IAAI,CAAC;IACd,CAAC;IAED,QAAQ,CAAC,QAAgB,EAAE,UAAkB,EAAE,MAAc;QAC3D,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;QAC9B,IAAI,CAAC,GAAG,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;IAC/B,CAAC;CACF"}

package/dist/fakeClient.d.ts

@@ -0,0 +1,48 @@
+import type { AxiosResponse, Client, ModuleInstallationOutputDTO, PlayerOnGameserverOutputWithRolesDTO, PlayerOutputWithRolesDTO } from '@takaro/apiclient';
+import { CurrencyLedger } from './currencyLedger.js';
+import { VariableStore } from './variableStore.js';
+import type { ClientStubs } from './stubbedClient.js';
+export declare class MissingFixtureError extends Error {
+    constructor(method: string, hint: string);
+}
+export { UnsupportedQueryError } from './query.js';
+export interface RecordedMessage {
+    gameServerId: string;
+    message: string;
+    recipientGameId?: string;
+}
+export interface FakeClientOptions {
+    gameServerId: string;
+    installations: ModuleInstallationOutputDTO[];
+    players: PlayerOutputWithRolesDTO[];
+    pogs: PlayerOnGameserverOutputWithRolesDTO[];
+    variables?: VariableStore;
+    currency?: CurrencyLedger;
+    settings?: Record<string, string>;
+    /** Read for TTL expiry and for `expiresAt` comparisons, so it tracks the VM's clock. */
+    now?: () => Date;
+}
+export declare function ok<T>(data: T): AxiosResponse<T>;
+export declare function single(data: unknown): AxiosResponse<never, any>;
+export interface PageMeta {
+    total?: number;
+    page?: number;
+    limit?: number;
+}
+export declare function paginated(results: unknown[], meta?: PageMeta): AxiosResponse<never, any>;
+export interface FakeClient {
+    /** Hand this to `executeVM({ clientOverride })`. */
+    asClient: Client;
+    stubs: ClientStubs;
+    variables: VariableStore;
+    currency: CurrencyLedger;
+    settings: Map<string, string>;
+    installations: ModuleInstallationOutputDTO[];
+    /** Every `gameServerControllerSendMessage` call, in order. */
+    messages: RecordedMessage[];
+    /** Just the messages addressed to one player — what `pm()` produces. */
+    pmsTo(gameId: string): string[];
+}
+/** @internal Exported for tests only. */
+export declare function createFakeClient(options: FakeClientOptions): FakeClient;
+//# sourceMappingURL=fakeClient.d.ts.map

package/dist/fakeClient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fakeClient.d.ts","sourceRoot":"","sources":["../src/fakeClient.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,aAAa,EACb,MAAM,EACN,2BAA2B,EAC3B,oCAAoC,EACpC,wBAAwB,EAEzB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAGnD,OAAO,KAAK,EAAE,WAAW,EAAmB,MAAM,oBAAoB,CAAC;AAWvE,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,YAAY,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAGvC;CACF;AAID,OAAO,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAEnD,MAAM,WAAW,eAAe;IAC9B,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,iBAAiB;IAChC,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,2BAA2B,EAAE,CAAC;IAC7C,OAAO,EAAE,wBAAwB,EAAE,CAAC;IACpC,IAAI,EAAE,oCAAoC,EAAE,CAAC;IAC7C,SAAS,CAAC,EAAE,aAAa,CAAC;IAC1B,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClC,wFAAwF;IACxF,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;CAClB;AASD,wBAAgB,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,GAAG,aAAa,CAAC,CAAC,CAAC,CAQ/C;AAQD,wBAAgB,MAAM,CAAC,IAAI,EAAE,OAAO,6BAEnC;AAED,MAAM,WAAW,QAAQ;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,wBAAgB,SAAS,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE,IAAI,GAAE,QAAa,6BAUhE;AAwBD,MAAM,WAAW,UAAU;IACzB,oDAAoD;IACpD,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,WAAW,CAAC;IACnB,SAAS,EAAE,aAAa,CAAC;IACzB,QAAQ,EAAE,cAAc,CAAC;IACzB,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9B,aAAa,EAAE,2BAA2B,EAAE,CAAC;IAC7C,8DAA8D;IAC9D,QAAQ,EAAE,eAAe,EAAE,CAAC;IAC5B,wEAAwE;IACxE,KAAK,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;CACjC;AAED,yCAAyC;AACzC,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,iBAAiB,GAAG,UAAU,CA8UvE"}