@clovnet/plugin-cli 0.2.2

package/templates/cashback/src/handlers/routes.ts

@@ -0,0 +1,188 @@
+import { z } from "zod";
+import type { PluginContext, PluginRequest } from "@clovnet/plugin-sdk";
+
+/**
+ * Player-facing cashback surface (mirrors the platform's reference cashback
+ * plugin): a dataset of per-player accrual periods, two query actions and an
+ * idempotent `claim` mutation that credits the BONUS bucket via the
+ * allowlisted `wallet.bonus_award` command — the only way a plugin may award
+ * money, with every wallet invariant (idempotency, immutable ledger, audit,
+ * outbox) applied by the platform.
+ */
+
+// `wallet.bonus_award` — referenced by string: an external plugin depends
+// only on the SDK + zod, never on platform packages.
+export const AWARD_BONUS_COMMAND = "wallet.bonus_award";
+
+// ── Dataset shape: one accrual period per player, per cycle ──────────────────
+export const accrualPeriodSchema = z.object({
+  periodId: z.string(),
+  playerId: z.string(),
+  /** accruing → claimable → claimed. */
+  status: z.enum(["accruing", "claimable", "claimed"]),
+  /** Decimal major units (e.g. 5 = €5.00); the wallet normalizes to 4dp. */
+  amount: z.number(),
+  currency: z.string(),
+  accruedAt: z.string(),
+  claimedAt: z.string().optional(),
+});
+export type AccrualPeriod = z.infer<typeof accrualPeriodSchema>;
+
+const periods = (ctx: PluginContext) => ctx.datasets.collection<AccrualPeriod>("accrual_periods");
+
+async function playerPeriods(ctx: PluginContext, playerId: string): Promise<AccrualPeriod[]> {
+  const result = await periods(ctx).query({ where: { playerId }, limit: 200 });
+  return result.records.map((r) => r.value);
+}
+
+// ── Action I/O schemas (drive the catalog descriptors + generated client) ────
+export const summaryOutputSchema = z.object({
+  currency: z.string(),
+  claimableAmount: z.number(),
+  claimedAmount: z.number(),
+  accruingAmount: z.number(),
+  periodCount: z.number(),
+});
+
+export const listPeriodsQuerySchema = z.object({
+  status: z.enum(["accruing", "claimable", "claimed"]).optional(),
+});
+export const listPeriodsOutputSchema = z.object({
+  periods: z.array(
+    z.object({
+      periodId: z.string(),
+      status: z.enum(["accruing", "claimable", "claimed"]),
+      amount: z.number(),
+      currency: z.string(),
+      accruedAt: z.string(),
+      claimedAt: z.string().optional(),
+    }),
+  ),
+});
+
+export const claimBodySchema = z.object({ periodId: z.string().min(1).max(191) }).strict();
+export const claimOutputSchema = z.object({
+  claimed: z.literal(true),
+  periodId: z.string(),
+  amount: z.number(),
+  currency: z.string(),
+});
+
+export const accrueBodySchema = z
+  .object({
+    playerId: z.string().min(1).max(191),
+    amount: z.number().positive(),
+    currency: z.string().length(3).optional(),
+  })
+  .strict();
+
+// ── Handlers ──────────────────────────────────────────────────────────────────
+export async function getSummary(req: PluginRequest, ctx: PluginContext) {
+  const playerId = req.player?.id;
+  if (!playerId) return { status: 401, body: { error: { code: "UNAUTHORIZED" } } };
+  const { payoutCurrency } = ctx.settings.get<{ payoutCurrency?: string }>();
+  const all = await playerPeriods(ctx, playerId);
+  const sum = (status: AccrualPeriod["status"]): number =>
+    all.filter((p) => p.status === status).reduce((n, p) => n + p.amount, 0);
+  return {
+    body: {
+      currency: payoutCurrency ?? "EUR",
+      claimableAmount: sum("claimable"),
+      claimedAmount: sum("claimed"),
+      accruingAmount: sum("accruing"),
+      periodCount: all.length,
+    },
+  };
+}
+
+export async function listPeriods(req: PluginRequest, ctx: PluginContext) {
+  const playerId = req.player?.id;
+  if (!playerId) return { status: 401, body: { error: { code: "UNAUTHORIZED" } } };
+  const query = req.query as z.infer<typeof listPeriodsQuerySchema>;
+  let all = await playerPeriods(ctx, playerId);
+  if (query.status) all = all.filter((p) => p.status === query.status);
+  all.sort((a, b) => a.accruedAt.localeCompare(b.accruedAt));
+  return {
+    body: {
+      periods: all.map((p) => ({
+        periodId: p.periodId,
+        status: p.status,
+        amount: p.amount,
+        currency: p.currency,
+        accruedAt: p.accruedAt,
+        ...(p.claimedAt ? { claimedAt: p.claimedAt } : {}),
+      })),
+    },
+  };
+}
+
+export async function claim(req: PluginRequest, ctx: PluginContext) {
+  const playerId = req.player?.id;
+  if (!playerId) return { status: 401, body: { error: { code: "UNAUTHORIZED" } } };
+  const body = req.body as z.infer<typeof claimBodySchema>;
+  const period = await periods(ctx).get(body.periodId);
+  // Not-found and not-owned look identical — never leak another player's data.
+  if (!period || period.playerId !== playerId) {
+    return { status: 404, body: { error: { code: "CASHBACK_PERIOD_NOT_FOUND" } } };
+  }
+  if (period.status !== "claimable") {
+    return {
+      status: 409,
+      body: { error: { code: "CASHBACK_NOT_CLAIMABLE", details: { status: period.status } } },
+    };
+  }
+
+  // The wallet idempotency key is PERIOD-SCOPED and deterministic, so
+  // concurrent/replayed claims of one period credit exactly once;
+  // `externalTransactionId = periodId` is the cross-key backstop.
+  const award = await ctx.commands.execute<{ idempotent: boolean }>({
+    name: AWARD_BONUS_COMMAND,
+    input: {
+      playerId,
+      amount: period.amount,
+      currency: period.currency,
+      idempotencyKey: `__PLUGIN_KEY__:claim:${period.periodId}`,
+      source: "__PLUGIN_KEY__",
+      externalTransactionId: period.periodId,
+    },
+  });
+
+  await periods(ctx).put(period.periodId, {
+    ...period,
+    status: "claimed",
+    claimedAt: new Date().toISOString(),
+  });
+  if (!award.idempotent) {
+    await ctx.events.emit({
+      name: "plugin.__PLUGIN_KEY__.claimed",
+      playerId,
+      payload: { periodId: period.periodId, amount: period.amount, currency: period.currency },
+    });
+  }
+  return {
+    body: { claimed: true as const, periodId: period.periodId, amount: period.amount, currency: period.currency },
+  };
+}
+
+/** Backoffice/ops route: mint a claimable cashback period for a player. */
+export async function accrue(req: PluginRequest, ctx: PluginContext) {
+  const body = req.body as z.infer<typeof accrueBodySchema>;
+  const { payoutCurrency } = ctx.settings.get<{ payoutCurrency?: string }>();
+  const now = new Date();
+  const periodId = `cb_${body.playerId}_${now.getTime().toString(36)}`;
+  const currency = body.currency ?? payoutCurrency ?? "EUR";
+  await periods(ctx).put(periodId, {
+    periodId,
+    playerId: body.playerId,
+    status: "claimable",
+    amount: body.amount,
+    currency,
+    accruedAt: now.toISOString(),
+  });
+  await ctx.events.emit({
+    name: "plugin.__PLUGIN_KEY__.accrued",
+    playerId: body.playerId,
+    payload: { periodId, amount: body.amount, currency },
+  });
+  return { status: 201, body: { periodId } };
+}

package/templates/cashback/src/index.ts

@@ -0,0 +1,128 @@
+import { definePlugin } from "@clovnet/plugin-sdk";
+import { settings } from "./settings.js";
+import { onConfigure, onInstall, onUninstall } from "./handlers/hooks.js";
+import {
+  AWARD_BONUS_COMMAND,
+  accrualPeriodSchema,
+  accrue,
+  accrueBodySchema,
+  claim,
+  claimBodySchema,
+  claimOutputSchema,
+  getSummary,
+  listPeriods,
+  listPeriodsOutputSchema,
+  listPeriodsQuerySchema,
+  summaryOutputSchema,
+} from "./handlers/routes.js";
+import { nightlyAccrual } from "./handlers/jobs.js";
+
+/**
+ * __PLUGIN_NAME__ — scaffolded from the `cashback` template (the platform's
+ * reference plugin): a plugin-private dataset, three player actions
+ * (`getSummary`/`listPeriods` queries + the idempotent `claim` mutation), an
+ * admin accrue route, a nightly cron and an account-slot frontend widget.
+ */
+export default definePlugin({
+  manifest: {
+    key: "__PLUGIN_KEY__",
+    name: "__PLUGIN_NAME__",
+    author: "you",
+    version: "0.1.0",
+    kind: "integration",
+    runtimeCompat: ">=0.1.0 <0.2.0",
+    description: "Player cashback accrual periods, claimable to the bonus bucket.",
+    permissions: {
+      // The ONLY wallet command a plugin may hold for awards — wallet.credit
+      // is hard-denied to plugins by the platform.
+      commands: [AWARD_BONUS_COMMAND],
+      events: {
+        subscribe: [],
+        emit: ["plugin.__PLUGIN_KEY__.accrued", "plugin.__PLUGIN_KEY__.claimed"],
+      },
+      // Short event types allowed to fan out to player sockets.
+      frontendEvents: ["__PLUGIN_KEY__.accrued", "__PLUGIN_KEY__.claimed"],
+    },
+    settings,
+    datasets: {
+      accrual_periods: {
+        schema: accrualPeriodSchema,
+        keyField: "periodId",
+        indexes: ["playerId", "status"],
+        maxRecords: 200_000,
+      },
+    },
+    routes: [
+      {
+        method: "GET",
+        path: "/summary",
+        surface: "player",
+        handler: "getSummary",
+        output: summaryOutputSchema,
+        rateLimit: { windowSec: 60, max: 120 },
+      },
+      {
+        method: "GET",
+        path: "/periods",
+        surface: "player",
+        handler: "listPeriods",
+        input: { query: listPeriodsQuerySchema },
+        output: listPeriodsOutputSchema,
+      },
+      {
+        method: "POST",
+        path: "/claim",
+        surface: "player",
+        handler: "claim",
+        input: { body: claimBodySchema },
+        output: claimOutputSchema,
+        idempotent: true,
+      },
+      {
+        method: "POST",
+        path: "/accrue",
+        surface: "admin",
+        handler: "accrue",
+        input: { body: accrueBodySchema },
+      },
+    ],
+    actions: [
+      {
+        key: "getSummary",
+        route: "GET /summary",
+        title: "Cashback summary",
+        description: "Claimable, claimed and accruing cashback totals for the player.",
+        kind: "query",
+      },
+      { key: "listPeriods", route: "GET /periods", title: "List cashback periods", kind: "query" },
+      {
+        key: "claim",
+        route: "POST /claim",
+        title: "Claim cashback",
+        description: "Credit a claimable period's cashback to the bonus balance.",
+        kind: "mutation",
+        idempotent: true,
+        emits: ["__PLUGIN_KEY__.claimed"],
+      },
+    ],
+    frontend: {
+      widgets: [
+        {
+          key: "__PLUGIN_KEY__-card",
+          title: "__PLUGIN_NAME__",
+          slot: "account",
+          dataAction: "getSummary",
+          actions: ["claim"],
+        },
+      ],
+    },
+    jobs: {
+      "nightly-accrual": { schedule: "0 3 * * *", handler: "nightly-accrual", timeoutSec: 300 },
+    },
+  },
+  hooks: { onInstall, onConfigure, onUninstall },
+  handlers: {
+    routes: { getSummary, listPeriods, claim, accrue },
+    jobs: { "nightly-accrual": nightlyAccrual },
+  },
+});

package/templates/cashback/src/settings.ts

@@ -0,0 +1,29 @@
+import { z } from "zod";
+import { settingsField, type PluginSettingsSchema } from "@clovnet/plugin-sdk";
+
+/**
+ * Tenant settings for the cashback program. `cashbackPercent` drives the
+ * nightly accrual sweep; the secret is an example write-only field (stored
+ * encrypted, never returned, never logged).
+ */
+export const settings: PluginSettingsSchema = {
+  fields: {
+    cashbackPercent: settingsField.number({
+      label: "Cashback percent",
+      description: "Percent of tracked losses accrued as claimable cashback.",
+      default: 5,
+      zod: z.number().min(0).max(25),
+    }),
+    payoutCurrency: settingsField.string({
+      label: "Payout currency",
+      description: "ISO currency the cashback is credited in.",
+      default: "EUR",
+      zod: z.string().length(3),
+    }),
+    reportingApiKey: settingsField.string({
+      label: "Reporting API key",
+      description: "Example write-only secret — read with ctx.secrets.get('reportingApiKey').",
+      secret: true,
+    }),
+  },
+};

package/templates/cashback/test/hooks.test.ts

@@ -0,0 +1,83 @@
+import { describe, expect, it } from "vitest";
+import { createTestContext } from "@clovnet/plugin-sdk/testing";
+import type { PluginRequest } from "@clovnet/plugin-sdk";
+import plugin from "../src/index.js";
+import { accrue, claim, getSummary } from "../src/handlers/routes.js";
+import { nightlyAccrual } from "../src/handlers/jobs.js";
+
+/**
+ * Unit tests on the in-memory test context: real permission enforcement,
+ * real dataset semantics, canned wallet results — no runtime, no docker,
+ * breakpoints work under `vitest --inspect`.
+ */
+const asRequest = (partial: Partial<PluginRequest>): PluginRequest =>
+  ({ params: {}, query: {}, headers: {}, ...partial }) as PluginRequest;
+
+function makeContext() {
+  return createTestContext(plugin, {
+    tenantId: "t-test",
+    settings: { cashbackPercent: 10, payoutCurrency: "EUR" },
+    secrets: { reportingApiKey: "test-key" },
+    commandResults: {
+      // Money commands NEVER execute in tests — canned result + recording.
+      "wallet.bonus_award": { idempotent: false, balances: { bonus: "5.0000" } },
+    },
+  });
+}
+
+describe("__PLUGIN_KEY__", () => {
+  it("accrues then claims exactly once through wallet.bonus_award", async () => {
+    const t = makeContext();
+    await t.runHook("onInstall");
+
+    const accrued = await accrue(
+      asRequest({ body: { playerId: "p1", amount: 5 }, actor: { type: "staff", id: "admin" } as never }),
+      t.ctx,
+    );
+    expect(accrued.status).toBe(201);
+    const periodId = (accrued.body as { periodId: string }).periodId;
+
+    const claimed = await claim(asRequest({ player: { id: "p1" }, body: { periodId } }), t.ctx);
+    expect(claimed.body).toMatchObject({ claimed: true, amount: 5, currency: "EUR" });
+
+    // The wallet command was recorded with a deterministic, period-scoped key.
+    expect(t.recorder.commands).toHaveLength(1);
+    expect(t.recorder.commands[0]).toMatchObject({ name: "wallet.bonus_award" });
+    expect(t.recorder.events.map((e) => e.name)).toEqual([
+      "plugin.__PLUGIN_KEY__.accrued",
+      "plugin.__PLUGIN_KEY__.claimed",
+    ]);
+
+    // A second claim of the SAME period is a 409, not a second credit.
+    const again = await claim(asRequest({ player: { id: "p1" }, body: { periodId } }), t.ctx);
+    expect(again.status).toBe(409);
+    expect(t.recorder.commands).toHaveLength(1);
+  });
+
+  it("never leaks another player's period", async () => {
+    const t = makeContext();
+    await accrue(asRequest({ body: { playerId: "p1", amount: 5 } }), t.ctx);
+    const summary = await getSummary(asRequest({ player: { id: "p2" } }), t.ctx);
+    expect(summary.body).toMatchObject({ claimableAmount: 0, periodCount: 0 });
+
+    const stolen = await claim(asRequest({ player: { id: "p2" }, body: { periodId: "cb_p1_x" } }), t.ctx);
+    expect(stolen.status).toBe(404);
+  });
+
+  it("nightly sweep flips accruing periods to claimable, idempotently", async () => {
+    const t = makeContext();
+    const periods = t.ctx.datasets.collection("accrual_periods");
+    await periods.put("cb_1", {
+      periodId: "cb_1",
+      playerId: "p1",
+      status: "accruing",
+      amount: 2.5,
+      currency: "EUR",
+      accruedAt: new Date().toISOString(),
+    });
+    await nightlyAccrual(t.ctx);
+    await nightlyAccrual(t.ctx); // idempotent
+    const record = await periods.get("cb_1");
+    expect(record).toMatchObject({ status: "claimable" });
+  });
+});

package/templates/cashback/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "verbatimModuleSyntax": true,
+    "skipLibCheck": true,
+    "noEmit": true,
+    "types": ["node"]
+  },
+  "include": ["src", "test"]
+}

package/templates/provider-skeleton/README.md

@@ -0,0 +1,63 @@
+# __PLUGIN_NAME__
+
+A CasinoWebEngine game-provider plugin skeleton, scaffolded with `cwe-plugin create`.
+
+## The golden path
+
+```bash
+pnpm create cwe-plugin my-cashback         # scaffold: manifest, handlers, tests, config
+cd my-cashback && pnpm install
+
+pnpm dev                                   # = cwe-plugin dev
+#  → first contact with the scaffold's preset `local` environment: the handshake verifies
+#    class=local + devHarness=true and pins its fingerprint  → green banner
+#  → doctor passes → sandbox tenant resolved → plugin installed+enabled (prompted)
+#  → esbuild watch starts, bundle hot-loaded, log stream attached
+#  → edit src/handlers/routes.ts, save → rebuilt + hot-reloaded in <2s, logs streaming live
+
+# in the dev session (keyboard):  i install · e enable · c configure · x disable · u uninstall
+#                                 r reload · d doctor · l clear · q quit
+# each lifecycle key prints a full hook trace: capability calls, events, audit refs, state
+
+pnpm test                                  # unit tests on hooks/handlers via the SDK test kit
+
+cwe-plugin lifecycle cycle                 # conformance sweep: install→enable→configure→disable→
+                                           # uninstall→reinstall, asserting idempotency + clean teardown
+
+cwe-plugin login                           # only needed for shared dev clusters / publishing
+cwe-plugin env add dev-eu https://dev-eu.cwe.dev && cwe-plugin env use dev-eu
+pnpm dev                                   # same loop against the shared cluster, per-dev sandbox
+
+pnpm publish:dev                           # = cwe-plugin publish — always the dev channel:
+                                           # doctor + codegen-diff gate + publish
+```
+
+## What's in this template
+
+| File | Purpose |
+|---|---|
+| `cwe-plugin.json` | project config: plugin key, entry, environments (committed — no secrets, ever) |
+| `src/index.ts` | `definePlugin({ manifest, hooks, handlers })` — the whole platform contract |
+| `src/settings.ts` | Zod-typed tenant settings (one secret field included) |
+| `src/adapter.ts` | the provider adapter — bets/settlements/rollbacks normalized into wallet commands |
+| `src/fake-backend.ts` | in-memory provider API stand-in (swap for real `ctx.http` calls) |
+| `src/handlers/hooks.ts` | lifecycle hooks (`onEnable` demands the apiKey secret) |
+| `src/handlers/routes.ts` | signature-verified `/tx` callback + public `/status` |
+| `src/handlers/jobs.ts` | nightly reconcile placeholder (dry-run with `cwe-plugin jobs run reconcile`) |
+| `settings.dev.json` | sandbox settings applied by `cwe-plugin lifecycle configure` / the `c` key |
+| `test/hooks.test.ts` | in-memory test-context examples — breakpoints work under `vitest --inspect` |
+
+## Useful commands
+
+```bash
+cwe-plugin env status                # am I pointed at a dev environment? auth? sandbox state?
+cwe-plugin invoke POST /tx --surface callback \
+  --body '{"type":"wager","playerId":"p1","roundId":"r1","amount":"5.0000","currency":"EUR","providerTxId":"ptx1"}'
+cwe-plugin settings set greeting=hi  # validated locally against the schema before it is sent
+cwe-plugin logs --level warn         # standalone log tail for a second terminal
+cwe-plugin doctor --remote           # full server-side validation
+```
+
+Machine-local state (pinned environment fingerprints, log cursors) lives in `.cwe/` — gitignored
+and always safe to delete. Credentials never touch the repo: `cwe-plugin login` stores them in the
+OS keychain.

package/templates/provider-skeleton/_gitignore

@@ -0,0 +1,3 @@
+node_modules/
+dist/
+.cwe/

package/templates/provider-skeleton/cwe-plugin.json

@@ -0,0 +1,9 @@
+{
+  "$schema": "https://cwe.dev/schemas/cwe-plugin.json",
+  "plugin": "__PLUGIN_KEY__",
+  "entry": "src/index.ts",
+  "environments": {
+    "local": { "runtimeUrl": "http://localhost:3000" }
+  },
+  "defaultEnvironment": "local"
+}

package/templates/provider-skeleton/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "cwe-plugin-__PLUGIN_KEY__",
+  "version": "0.1.0",
+  "description": "__PLUGIN_NAME__ \u2014 a CasinoWebEngine plugin",
+  "private": true,
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "dev": "cwe-plugin dev",
+    "doctor": "cwe-plugin doctor",
+    "test": "vitest run",
+    "build": "cwe-plugin build",
+    "codegen": "cwe-plugin codegen client",
+    "publish:dev": "cwe-plugin publish"
+  },
+  "dependencies": {
+    "@clovnet/plugin-sdk": "^0.1.4"
+  },
+  "peerDependencies": {
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@clovnet/plugin-cli": "^0.2.0",
+    "@types/node": "^20.16.5",
+    "typescript": "^5.6.2",
+    "vitest": "^2.1.1",
+    "zod": "^3.23.8"
+  }
+}

package/templates/provider-skeleton/settings.dev.json

@@ -0,0 +1,10 @@
+{
+  "values": {
+    "baseUrl": "https://api.__PLUGIN_KEY__.example",
+    "operatorId": "op-demo"
+  },
+  "secrets": {
+    "apiKey": "dev-api-key",
+    "callbackSigningSecret": "dev-signing-secret"
+  }
+}