@jskit-ai/rewarded-core 0.1.120

package/README.md

@@ -0,0 +1,149 @@
+# @jskit-ai/rewarded-core
+
+Server runtime for Rewarded unlock gates.
+
+## Package Shape
+
+This package installs:
+
+- four CRUD-owned server providers, one per persisted table
+- one workflow provider for the rewarded gate API
+
+The persisted tables are:
+
+- `rewarded_rules`
+- `rewarded_provider_configs`
+- `rewarded_watch_sessions`
+- `rewarded_unlock_receipts`
+
+The package keeps the CRUD ownership strict:
+
+- rules and provider configs are `workspace`-owned
+- watch sessions and unlock receipts are `workspace_user`-owned
+
+Every owned row carries direct owner columns. The module does not rely on inherited ownership through parent joins.
+
+## What It Does
+
+The workflow provider exposes four workspace-scoped app routes:
+
+- `GET /api/w/:workspaceSlug/rewarded/current`
+- `POST /api/w/:workspaceSlug/rewarded/start`
+- `POST /api/w/:workspaceSlug/rewarded/grant`
+- `POST /api/w/:workspaceSlug/rewarded/close`
+
+These are plain workflow endpoints, not CRUD JSON:API endpoints.
+
+The flow is:
+
+1. `current` decides whether the gate is enabled, blocked, or already unlocked.
+2. `start` creates a watch session when a reward is required.
+3. `grant` marks the session rewarded and creates an unlock receipt.
+4. `close` closes a started session without granting access.
+
+Day 0 is intentionally app-surface-only for the rewarded workflow. Rules and provider configs should therefore use `surface = "app"` for the active gate rows.
+
+## Required Data
+
+Day-0 configuration lives in the CRUD-owned tables.
+
+At minimum, apps need:
+
+- a `rewarded_rules` row for the target `gateKey`
+- a matching enabled `rewarded_provider_configs` row for the surface
+
+Important config fields:
+
+- `rewarded_rules.gate_key`
+- `rewarded_rules.surface`
+- `rewarded_rules.unlock_minutes`
+- `rewarded_rules.cooldown_minutes`
+- `rewarded_rules.daily_limit`
+- `rewarded_provider_configs.surface`
+- `rewarded_provider_configs.placement`
+- `rewarded_provider_configs.provider`
+
+The application selects `provider` and `placement` for its delivery adapter.
+The workflow does not interpret them or choose a default provider. For the
+Google application pattern use `provider = "google-publisher-tag"` and the ad unit
+path as `placement`.
+
+## Protecting Server Features
+
+Protected server mutations should use the exported helper:
+
+```js
+import { requireRewardedUnlock } from "@jskit-ai/rewarded-core/server/requireRewardedUnlock";
+```
+
+The dedicated manual page is:
+
+- [docs/protecting-server-actions.md](docs/protecting-server-actions.md)
+
+That page shows the exact service and provider wiring pattern.
+
+## Grant authorization
+
+The application must supply capability `rewarded.grant-policy` with an
+`authorizeGrant({ session, context, trx })` function. Direct service composition
+supplies the same function as `authorizeGrant`. Missing policy fails at setup;
+only the literal result `true` permits a grant. False, absent or other results
+reject it before any watch-session update or receipt creation.
+
+The workflow loads the session through its owned repository, then passes that
+stored session, the server request context and the current transaction to policy.
+It never accepts a client approval flag or replacement gate identity. The policy
+runs for repeated grant requests too. Keep policy local and bounded within the
+transaction; use the application's trusted eligibility or verification records.
+A policy exception propagates as failure rather than silently allowing a grant.
+
+The Google browser pattern supplies delivery only. Its callbacks are not a
+server authorization implementation. The application must decide which reward
+claims it accepts; the library supplies neither provider-proof verification nor
+a permissive default.
+
+## Policy Model
+
+This module is designed for rewarded unlocks, not for blocking all normal app use on boot.
+
+Recommended usage:
+
+- unlock bonus actions
+- unlock extra quota
+- unlock a temporary feature window
+
+Do not treat it as a hard requirement for baseline product use unless the ad provider policy clearly allows that.
+
+## Install Notes
+
+The package declares its four initial schema migrations under `migrations/`.
+Run them through the application's existing database migration operation.
+
+The package does not add day-0 settings pages automatically. Configuration can stay manual or be layered with app-specific UI later.
+
+## Manual V0 migration
+
+Replace `@jskit-ai/google-rewarded-core` with `@jskit-ai/rewarded-core` and
+`@jskit-ai/google-rewarded-web` with `@jskit-ai/rewarded-web`. Update imports
+(`requireRewardedUnlock`, `createRewardedRuntime`, `useRewardedRuntime`),
+`Rewarded*` provider names, `rewarded.*` server capabilities, `client.rewarded`
+and `/api/w/:workspaceSlug/rewarded/*` routes. Register application-owned
+`client.rewarded-delivery` and `rewarded.grant-policy` providers as described
+in these packages. There is no implicit grant approval for older apps.
+
+For disposable prerelease data, recreate the four tables through the new
+migrations. If retaining data, stop writers, back up the database and manually
+rename each `google_rewarded_*` table to `rewarded_*`, preserving IDs, owner
+columns and foreign-key relationships. In the provider configuration table,
+rename `ad_unit_path` to `placement` and replace `script_mode` with required
+`provider` values chosen for the application; existing GPT rows use
+`google-publisher-tag`. Remove the old column/default. Reconcile the application's
+migration records so initial table creation is not replayed against retained
+schema; verify indexes, constraints and ownership with its database tools before
+resuming writers. Decide explicitly whether to retain active watch sessions and
+unlock receipts. No library migration shim, alias, old-table reader or dual write
+performs this conversion.
+
+The package manifest lists application-owned inputs in both `capabilities.requires`
+and `capabilities.applicationRequires`. The latter identifies who supplies them;
+it does not make the runtime dependency optional or provide a default.

package/docs/protecting-server-actions.md

@@ -0,0 +1,190 @@
+# Protecting Server Actions With `requireRewardedUnlock()`
+
+This is the manual page for the server helper exported by:
+
+```js
+@jskit-ai/rewarded-core/server/requireRewardedUnlock
+```
+
+Use this helper when a feature is:
+
+- allowed in principle for the actor
+- but temporarily gated behind a rewarded unlock
+
+Do not use it as a permission system.
+
+The correct split is:
+
+- permissions decide whether the actor may ever do the thing
+- rewarded gates decide whether the actor must unlock the thing right now
+
+## What The Helper Does
+
+`requireRewardedUnlock()` calls `rewarded.core.service.getCurrentState(...)` and then enforces one simple rule:
+
+- if the gate is already unlocked, it returns the gate state
+- if the gate is not configured and `requireConfigured` is not enabled, it returns the gate state
+- otherwise it throws an `AppError`
+
+This means the helper is a truth-enforcement seam for protected server operations.
+
+The UI should still call the web runtime first for user experience, but the protected server operation must also check the gate so users cannot bypass it by calling the endpoint directly.
+
+## Import Path
+
+```js
+import { requireRewardedUnlock } from "@jskit-ai/rewarded-core/server/requireRewardedUnlock";
+```
+
+## Basic Service Pattern
+
+Inject `rewarded.core.service` into your own feature service, then call the helper before the protected mutation.
+
+Example:
+
+```js
+import { requireRewardedUnlock } from "@jskit-ai/rewarded-core/server/requireRewardedUnlock";
+
+function createProgressLoggingService({
+  rewardedService,
+  workoutLogRepository
+} = {}) {
+  async function logProgress(input = {}, options = {}) {
+    await requireRewardedUnlock(
+      rewardedService,
+      {
+        gateKey: "progress-logging",
+        workspaceSlug: input.workspaceSlug
+      },
+      {
+        context: options.context,
+        errorMessage: "Watch a rewarded ad before logging progress."
+      }
+    );
+
+    return workoutLogRepository.create(input, options);
+  }
+
+  return Object.freeze({
+    logProgress
+  });
+}
+```
+
+## Provider Wiring Pattern
+
+Inject the rewarded service from the container the same way as any other JSKIT runtime service.
+
+Example:
+
+```js
+app.service(
+  "convict.progress-logging.service",
+  (scope) => createProgressLoggingService({
+    rewardedService: scope.make("rewarded.core.service"),
+    workoutLogRepository: scope.make("convict.workout-log.repository")
+  })
+);
+```
+
+## Exact Helper Signature
+
+```js
+await requireRewardedUnlock(
+  rewardedService,
+  {
+    gateKey,
+    workspaceSlug
+  },
+  {
+    context,
+    requireConfigured,
+    errorCode,
+    errorMessage
+  }
+);
+```
+
+Arguments:
+
+- `rewardedService`
+  - must expose `getCurrentState(input, { context })`
+- first object
+  - `gateKey`: required gate identifier
+  - `workspaceSlug`: required for the current workspace gate
+- second object
+  - `context`: the normal JSKIT action/service context
+  - `requireConfigured`: fail closed when no rule/provider config exists
+  - `errorCode`: optional override for the thrown `AppError.code`
+  - `errorMessage`: optional override for the thrown `AppError.message`
+
+## Default Behavior
+
+The helper is intentionally permissive when the rewarded gate is not configured.
+
+By default:
+
+- `reason = "rule-not-configured"` passes
+- `reason = "provider-not-configured"` passes
+
+Why:
+
+- day-0 apps may install the package before creating live rules/config rows
+- you do not want every protected feature to break during setup or partial rollout
+
+If you want the protected operation to fail closed until configuration exists, set:
+
+```js
+requireConfigured: true
+```
+
+## When The Helper Throws
+
+The helper throws `AppError` with `details.rewardedGate` containing the full gate state.
+
+Important built-in failure cases:
+
+- `reward-required`
+  - status: `423`
+  - code: `rewarded_unlock_required`
+- `cooldown-active`
+  - status: `423`
+  - code: `rewarded_cooldown_active`
+- `daily-limit-reached`
+  - status: `423`
+  - code: `rewarded_daily_limit_reached`
+- `rule-not-configured` or `provider-not-configured` with `requireConfigured: true`
+  - status: `503`
+  - code: `rewarded_not_configured`
+
+## What The Helper Returns
+
+On success, the helper returns the gate state from `rewardedService.getCurrentState(...)`.
+
+That lets your service inspect the unlock window if it wants to log or branch on it, for example:
+
+```js
+const gateState = await requireRewardedUnlock(...);
+const unlockedUntil = gateState.unlock?.unlockedUntil || null;
+```
+
+## Recommended Calling Order
+
+For a protected feature operation:
+
+1. run normal permission / ownership checks
+2. run `requireRewardedUnlock(...)`
+3. perform the real mutation
+
+Do not invert that order.
+
+## What Not To Do
+
+Do not:
+
+- model rewarded gates as permissions
+- skip the server check because the client already opened the gate
+- rely on route visibility as the rewarded gate
+- duplicate the raw `reason` checks in every feature service
+
+Use the helper instead of open-coding that logic.

package/migrations/rewarded_provider_configs_initial.cjs

@@ -0,0 +1,27 @@
+const TABLE_NAME = "rewarded_provider_configs";
+
+exports.up = async function up(knex) {
+  const hasCrudTable = await knex.schema.hasTable(TABLE_NAME);
+  if (hasCrudTable) {
+    return;
+  }
+
+  await knex.schema.createTable(TABLE_NAME, (table) => {
+    table.bigIncrements("id").unsigned().primary();
+    table.bigInteger("workspace_id").unsigned().notNullable();
+    table.string("surface", 64).notNullable();
+    table.boolean("enabled").notNullable().defaultTo(true);
+    table.string("placement", 255).notNullable();
+    table.string("provider", 64).notNullable();
+    table.timestamp("created_at").notNullable().defaultTo(knex.fn.now());
+    table.timestamp("updated_at").notNullable().defaultTo(knex.raw("CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP"));
+    table.index(["workspace_id"], "idx_rewarded_provider_configs_workspace");
+    table.unique(["workspace_id","surface"], "uq_rewarded_provider_configs_workspace_surface");
+    table.foreign(["workspace_id"], "fk_rewarded_provider_configs_workspace").references(["id"]).inTable("workspaces").onUpdate("RESTRICT").onDelete("CASCADE");
+  });
+
+};
+
+exports.down = async function down(knex) {
+  await knex.schema.dropTableIfExists(TABLE_NAME);
+};

package/migrations/rewarded_rules_initial.cjs

@@ -0,0 +1,31 @@
+const TABLE_NAME = "rewarded_rules";
+
+exports.up = async function up(knex) {
+  const hasCrudTable = await knex.schema.hasTable(TABLE_NAME);
+  if (hasCrudTable) {
+    return;
+  }
+
+  await knex.schema.createTable(TABLE_NAME, (table) => {
+    table.bigIncrements("id").unsigned().primary();
+    table.bigInteger("workspace_id").unsigned().notNullable();
+    table.string("gate_key", 120).notNullable();
+    table.string("surface", 64).notNullable();
+    table.boolean("enabled").notNullable().defaultTo(true);
+    table.integer("unlock_minutes").unsigned().notNullable().defaultTo(30);
+    table.integer("cooldown_minutes").unsigned().notNullable().defaultTo(0);
+    table.integer("daily_limit").unsigned().nullable();
+    table.string("title", 160).notNullable().defaultTo("");
+    table.text("description").nullable();
+    table.timestamp("created_at").notNullable().defaultTo(knex.fn.now());
+    table.timestamp("updated_at").notNullable().defaultTo(knex.raw("CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP"));
+    table.index(["workspace_id"], "idx_rewarded_rules_workspace");
+    table.unique(["workspace_id","gate_key"], "uq_rewarded_rules_workspace_gate");
+    table.foreign(["workspace_id"], "fk_rewarded_rules_workspace").references(["id"]).inTable("workspaces").onUpdate("RESTRICT").onDelete("CASCADE");
+  });
+
+};
+
+exports.down = async function down(knex) {
+  await knex.schema.dropTableIfExists(TABLE_NAME);
+};

package/migrations/rewarded_unlock_receipts_initial.cjs

@@ -0,0 +1,35 @@
+const TABLE_NAME = "rewarded_unlock_receipts";
+
+exports.up = async function up(knex) {
+  const hasCrudTable = await knex.schema.hasTable(TABLE_NAME);
+  if (hasCrudTable) {
+    return;
+  }
+
+  await knex.schema.createTable(TABLE_NAME, (table) => {
+    table.bigIncrements("id").unsigned().primary();
+    table.bigInteger("workspace_id").unsigned().notNullable();
+    table.bigInteger("user_id").unsigned().notNullable();
+    table.string("gate_key", 120).notNullable();
+    table.bigInteger("provider_config_id").unsigned().nullable();
+    table.bigInteger("watch_session_id").unsigned().nullable();
+    table.timestamp("granted_at").notNullable().defaultTo(knex.fn.now());
+    table.timestamp("unlocked_until").notNullable();
+    table.timestamp("created_at").notNullable().defaultTo(knex.fn.now());
+    table.index(["user_id"], "fk_rewarded_unlock_receipts_user");
+    table.index(["gate_key"], "idx_rewarded_unlock_receipts_gate");
+    table.index(["provider_config_id"], "idx_rewarded_unlock_receipts_provider_config");
+    table.index(["unlocked_until"], "idx_rewarded_unlock_receipts_unlocked_until");
+    table.index(["watch_session_id"], "idx_rewarded_unlock_receipts_watch_session");
+    table.index(["workspace_id","user_id"], "idx_rewarded_unlock_receipts_workspace_user");
+    table.foreign(["provider_config_id"], "fk_rewarded_unlock_receipts_provider_config").references(["id"]).inTable("rewarded_provider_configs").onUpdate("RESTRICT").onDelete("SET NULL");
+    table.foreign(["user_id"], "fk_rewarded_unlock_receipts_user").references(["id"]).inTable("users").onUpdate("RESTRICT").onDelete("CASCADE");
+    table.foreign(["watch_session_id"], "fk_rewarded_unlock_receipts_watch_session").references(["id"]).inTable("rewarded_watch_sessions").onUpdate("RESTRICT").onDelete("SET NULL");
+    table.foreign(["workspace_id"], "fk_rewarded_unlock_receipts_workspace").references(["id"]).inTable("workspaces").onUpdate("RESTRICT").onDelete("CASCADE");
+  });
+
+};
+
+exports.down = async function down(knex) {
+  await knex.schema.dropTableIfExists(TABLE_NAME);
+};

package/migrations/rewarded_watch_sessions_initial.cjs

@@ -0,0 +1,36 @@
+const TABLE_NAME = "rewarded_watch_sessions";
+
+exports.up = async function up(knex) {
+  const hasCrudTable = await knex.schema.hasTable(TABLE_NAME);
+  if (hasCrudTable) {
+    return;
+  }
+
+  await knex.schema.createTable(TABLE_NAME, (table) => {
+    table.bigIncrements("id").unsigned().primary();
+    table.bigInteger("workspace_id").unsigned().notNullable();
+    table.bigInteger("user_id").unsigned().notNullable();
+    table.string("gate_key", 120).notNullable();
+    table.bigInteger("provider_config_id").unsigned().nullable();
+    table.string("status", 32).notNullable().defaultTo("started");
+    table.timestamp("started_at").notNullable().defaultTo(knex.fn.now());
+    table.timestamp("rewarded_at").nullable();
+    table.timestamp("completed_at").nullable();
+    table.timestamp("closed_at").nullable();
+    table.timestamp("created_at").notNullable().defaultTo(knex.fn.now());
+    table.timestamp("updated_at").notNullable().defaultTo(knex.raw("CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP"));
+    table.index(["user_id"], "fk_rewarded_watch_sessions_user");
+    table.index(["gate_key"], "idx_rewarded_watch_sessions_gate");
+    table.index(["provider_config_id"], "idx_rewarded_watch_sessions_provider_config");
+    table.index(["status"], "idx_rewarded_watch_sessions_status");
+    table.index(["workspace_id","user_id"], "idx_rewarded_watch_sessions_workspace_user");
+    table.foreign(["provider_config_id"], "fk_rewarded_watch_sessions_provider_config").references(["id"]).inTable("rewarded_provider_configs").onUpdate("RESTRICT").onDelete("SET NULL");
+    table.foreign(["user_id"], "fk_rewarded_watch_sessions_user").references(["id"]).inTable("users").onUpdate("RESTRICT").onDelete("CASCADE");
+    table.foreign(["workspace_id"], "fk_rewarded_watch_sessions_workspace").references(["id"]).inTable("workspaces").onUpdate("RESTRICT").onDelete("CASCADE");
+  });
+
+};
+
+exports.down = async function down(knex) {
+  await knex.schema.dropTableIfExists(TABLE_NAME);
+};

package/package.json

@@ -0,0 +1,130 @@
+{
+  "name": "@jskit-ai/rewarded-core",
+  "version": "0.1.120",
+  "type": "module",
+  "exports": {
+    "./shared": "./src/shared/index.js",
+    "./server/actions": "./src/server/actions.js",
+    "./server/requireRewardedUnlock": "./src/server/support/requireRewardedUnlock.js"
+  },
+  "description": "Rewarded workflow runtime plus internal CRUD providers for rules, provider configs, watch sessions, and unlock receipts.",
+  "jskit": {
+    "kind": "runtime",
+    "capabilities": {
+      "provides": [
+        "rewarded.rules",
+        "rewarded.provider-configs",
+        "rewarded.watch-sessions",
+        "rewarded.unlock-receipts",
+        "rewarded.core"
+      ],
+      "requires": [
+        "runtime.actions",
+        "runtime.database",
+        "runtime.http",
+        "runtime.json-rest-api",
+        "rewarded.grant-policy"
+      ],
+      "applicationRequires": [
+        "rewarded.grant-policy"
+      ]
+    },
+    "runtime": {
+      "server": {
+        "providers": [
+          {
+            "entrypoint": "src/server/RewardedResources.js",
+            "export": "RewardedRulesFeature"
+          },
+          {
+            "entrypoint": "src/server/RewardedResources.js",
+            "export": "RewardedProviderConfigsFeature"
+          },
+          {
+            "entrypoint": "src/server/RewardedResources.js",
+            "export": "RewardedWatchSessionsFeature"
+          },
+          {
+            "entrypoint": "src/server/RewardedResources.js",
+            "export": "RewardedUnlockReceiptsFeature"
+          },
+          {
+            "entrypoint": "src/server/RewardedCoreProvider.js",
+            "export": "RewardedCoreFeature"
+          }
+        ]
+      },
+      "client": {
+        "providers": []
+      }
+    },
+    "metadata": {
+      "jskit": {
+        "tableOwnership": {
+          "tables": [
+            {
+              "tableName": "rewarded_rules",
+              "providerEntrypoint": "src/server/RewardedResources.js",
+              "ownershipFilter": "workspace"
+            },
+            {
+              "tableName": "rewarded_provider_configs",
+              "providerEntrypoint": "src/server/RewardedResources.js",
+              "ownershipFilter": "workspace"
+            },
+            {
+              "tableName": "rewarded_watch_sessions",
+              "providerEntrypoint": "src/server/RewardedResources.js",
+              "ownershipFilter": "workspace_user"
+            },
+            {
+              "tableName": "rewarded_unlock_receipts",
+              "providerEntrypoint": "src/server/RewardedResources.js",
+              "ownershipFilter": "workspace_user"
+            }
+          ]
+        }
+      },
+      "apiSummary": {
+        "surfaces": [
+          {
+            "subpath": "./shared",
+            "summary": "Exports Rewarded shared CRUD resources."
+          },
+          {
+            "subpath": "./server/actions",
+            "summary": "Exports Rewarded workflow action identifiers and validators."
+          },
+          {
+            "subpath": "./server/requireRewardedUnlock",
+            "summary": "Exports the server helper that enforces a rewarded unlock before a protected feature action continues."
+          }
+        ],
+        "capabilities": [
+          "rewarded.rules",
+          "rewarded.provider-configs",
+          "rewarded.watch-sessions",
+          "rewarded.unlock-receipts",
+          "rewarded.core"
+        ]
+      }
+    },
+    "migrations": {
+      "directories": [
+        "migrations"
+      ]
+    }
+  },
+  "dependencies": {
+    "@jskit-ai/crud-core": "0.1.195",
+    "@jskit-ai/database-runtime": "0.1.184",
+    "@jskit-ai/json-rest-api-core": "0.1.128",
+    "@jskit-ai/resource-crud-core": "0.1.126",
+    "@jskit-ai/workspaces-core": "0.1.162"
+  },
+  "peerDependencies": {
+    "@jskit-ai/auth-core": "0.1.182",
+    "@jskit-ai/http-runtime": "0.1.182",
+    "@jskit-ai/kernel": "0.1.184"
+  }
+}

package/src/server/RewardedCoreProvider.js

@@ -0,0 +1,44 @@
+import { defineFeature } from "@jskit-ai/kernel/server/features";
+
+import { createService } from "./service.js";
+import { createRewardedActions } from "./actions.js";
+import { registerRoutes } from "./registerRoutes.js";
+
+const RewardedCoreFeature = defineFeature({
+  id: "rewarded.core",
+  domain: "rewarded",
+  requires: {
+    http: "runtime.http",
+    grantPolicy: "rewarded.grant-policy",
+    providerConfigs: "rewarded.provider-configs",
+    rules: "rewarded.rules",
+    unlockReceipts: "rewarded.unlock-receipts",
+    watchSessions: "rewarded.watch-sessions"
+  },
+  provides: {
+    rewarded: "rewarded.core"
+  },
+  setup({ http, grantPolicy, providerConfigs, rules, unlockReceipts, watchSessions }) {
+    if (typeof grantPolicy.authorizeGrant !== "function") {
+      throw new TypeError("rewarded.grant-policy requires authorizeGrant.");
+    }
+    const rewarded = createService({
+      authorizeGrant: (input) => grantPolicy.authorizeGrant(input),
+      rewardedRulesRepository: rules.repository,
+      rewardedProviderConfigsRepository: providerConfigs.repository,
+      rewardedWatchSessionsRepository: watchSessions.repository,
+      rewardedUnlockReceiptsRepository: unlockReceipts.repository
+    });
+    registerRoutes(http.router, {
+      routeOwnershipFilter: "workspace_user",
+      routeSurface: "app",
+      routeRelativePath: "rewarded"
+    });
+    return { rewarded };
+  },
+  actions({ rewarded }) {
+    return createRewardedActions({ rewarded });
+  }
+});
+
+export { RewardedCoreFeature };