@jskit-ai/google-rewarded-core 0.1.1

package/README.md

@@ -0,0 +1,98 @@
+# @jskit-ai/google-rewarded-core
+
+Server runtime for Google 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:
+
+- `google_rewarded_rules`
+- `google_rewarded_provider_configs`
+- `google_rewarded_watch_sessions`
+- `google_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/google-rewarded/current`
+- `POST /api/w/:workspaceSlug/google-rewarded/start`
+- `POST /api/w/:workspaceSlug/google-rewarded/grant`
+- `POST /api/w/:workspaceSlug/google-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 `google_rewarded_rules` row for the target `gateKey`
+- a matching enabled `google_rewarded_provider_configs` row for the surface
+
+Important config fields:
+
+- `google_rewarded_rules.gate_key`
+- `google_rewarded_rules.surface`
+- `google_rewarded_rules.unlock_minutes`
+- `google_rewarded_rules.cooldown_minutes`
+- `google_rewarded_rules.daily_limit`
+- `google_rewarded_provider_configs.surface`
+- `google_rewarded_provider_configs.ad_unit_path`
+- `google_rewarded_provider_configs.script_mode`
+
+Day 0 assumes GPT rewarded ads for web, so `script_mode` should stay aligned with that flow.
+
+## Protecting Server Features
+
+Protected server mutations should use the exported helper:
+
+```js
+import { requireGoogleRewardedUnlock } from "@jskit-ai/google-rewarded-core/server/requireGoogleRewardedUnlock";
+```
+
+The dedicated manual page is:
+
+- [docs/protecting-server-actions.md](/home/merc/Development/current/jskit-ai/packages/google-rewarded-core/docs/protecting-server-actions.md)
+
+That page shows the exact service and provider wiring pattern.
+
+## 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
+
+When an app adds this package, JSKIT installs the four schema migrations from `templates/migrations/`.
+
+The package does not add day-0 settings pages automatically. Configuration can stay manual or be layered with app-specific UI later.

package/docs/protecting-server-actions.md

@@ -0,0 +1,190 @@
+# Protecting Server Actions With `requireGoogleRewardedUnlock()`
+
+This is the manual page for the server helper exported by:
+
+```js
+@jskit-ai/google-rewarded-core/server/requireGoogleRewardedUnlock
+```
+
+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
+
+`requireGoogleRewardedUnlock()` calls `google-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 { requireGoogleRewardedUnlock } from "@jskit-ai/google-rewarded-core/server/requireGoogleRewardedUnlock";
+```
+
+## Basic Service Pattern
+
+Inject `google-rewarded.core.service` into your own feature service, then call the helper before the protected mutation.
+
+Example:
+
+```js
+import { requireGoogleRewardedUnlock } from "@jskit-ai/google-rewarded-core/server/requireGoogleRewardedUnlock";
+
+function createProgressLoggingService({
+  googleRewardedService,
+  workoutLogRepository
+} = {}) {
+  async function logProgress(input = {}, options = {}) {
+    await requireGoogleRewardedUnlock(
+      googleRewardedService,
+      {
+        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({
+    googleRewardedService: scope.make("google-rewarded.core.service"),
+    workoutLogRepository: scope.make("convict.workout-log.repository")
+  })
+);
+```
+
+## Exact Helper Signature
+
+```js
+await requireGoogleRewardedUnlock(
+  googleRewardedService,
+  {
+    gateKey,
+    workspaceSlug
+  },
+  {
+    context,
+    requireConfigured,
+    errorCode,
+    errorMessage
+  }
+);
+```
+
+Arguments:
+
+- `googleRewardedService`
+  - 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: `google_rewarded_unlock_required`
+- `cooldown-active`
+  - status: `423`
+  - code: `google_rewarded_cooldown_active`
+- `daily-limit-reached`
+  - status: `423`
+  - code: `google_rewarded_daily_limit_reached`
+- `rule-not-configured` or `provider-not-configured` with `requireConfigured: true`
+  - status: `503`
+  - code: `google_rewarded_not_configured`
+
+## What The Helper Returns
+
+On success, the helper returns the gate state from `googleRewardedService.getCurrentState(...)`.
+
+That lets your service inspect the unlock window if it wants to log or branch on it, for example:
+
+```js
+const gateState = await requireGoogleRewardedUnlock(...);
+const unlockedUntil = gateState.unlock?.unlockedUntil || null;
+```
+
+## Recommended Calling Order
+
+For a protected feature operation:
+
+1. run normal permission / ownership checks
+2. run `requireGoogleRewardedUnlock(...)`
+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/package.descriptor.mjs

@@ -0,0 +1,186 @@
+export default Object.freeze({
+  packageVersion: 1,
+  packageId: "@jskit-ai/google-rewarded-core",
+  version: "0.1.1",
+  kind: "runtime",
+  description: "Google rewarded workflow runtime plus internal CRUD providers for rules, provider configs, watch sessions, and unlock receipts.",
+  dependsOn: [
+    "@jskit-ai/auth-core",
+    "@jskit-ai/crud-core",
+    "@jskit-ai/database-runtime",
+    "@jskit-ai/http-runtime",
+    "@jskit-ai/json-rest-api-core",
+    "@jskit-ai/kernel",
+    "@jskit-ai/resource-crud-core",
+    "@jskit-ai/workspaces-core"
+  ],
+  capabilities: {
+    provides: [
+      "crud.google-rewarded-rules",
+      "crud.google-rewarded-provider-configs",
+      "crud.google-rewarded-watch-sessions",
+      "crud.google-rewarded-unlock-receipts",
+      "google-rewarded.core"
+    ],
+    requires: [
+      "runtime.actions",
+      "runtime.database",
+      "auth.policy",
+      "json-rest-api.core"
+    ]
+  },
+  runtime: {
+    server: {
+      providers: [
+        {
+          entrypoint: "src/server/rules/GoogleRewardedRulesProvider.js",
+          export: "GoogleRewardedRulesProvider"
+        },
+        {
+          entrypoint: "src/server/providerConfigs/GoogleRewardedProviderConfigsProvider.js",
+          export: "GoogleRewardedProviderConfigsProvider"
+        },
+        {
+          entrypoint: "src/server/watchSessions/GoogleRewardedWatchSessionsProvider.js",
+          export: "GoogleRewardedWatchSessionsProvider"
+        },
+        {
+          entrypoint: "src/server/unlockReceipts/GoogleRewardedUnlockReceiptsProvider.js",
+          export: "GoogleRewardedUnlockReceiptsProvider"
+        },
+        {
+          entrypoint: "src/server/GoogleRewardedCoreProvider.js",
+          export: "GoogleRewardedCoreProvider"
+        }
+      ]
+    },
+    client: {
+      providers: []
+    }
+  },
+  metadata: {
+    jskit: {
+      scaffoldShape: "crud-server-v1",
+      tableOwnership: {
+        tables: [
+          {
+            tableName: "google_rewarded_rules",
+            provenance: "crud-server-generator",
+            ownerKind: "crud-package",
+            providerEntrypoint: "src/server/rules/GoogleRewardedRulesProvider.js",
+            ownershipFilter: "workspace"
+          },
+          {
+            tableName: "google_rewarded_provider_configs",
+            provenance: "crud-server-generator",
+            ownerKind: "crud-package",
+            providerEntrypoint: "src/server/providerConfigs/GoogleRewardedProviderConfigsProvider.js",
+            ownershipFilter: "workspace"
+          },
+          {
+            tableName: "google_rewarded_watch_sessions",
+            provenance: "crud-server-generator",
+            ownerKind: "crud-package",
+            providerEntrypoint: "src/server/watchSessions/GoogleRewardedWatchSessionsProvider.js",
+            ownershipFilter: "workspace_user"
+          },
+          {
+            tableName: "google_rewarded_unlock_receipts",
+            provenance: "crud-server-generator",
+            ownerKind: "crud-package",
+            providerEntrypoint: "src/server/unlockReceipts/GoogleRewardedUnlockReceiptsProvider.js",
+            ownershipFilter: "workspace_user"
+          }
+        ]
+      }
+    },
+    apiSummary: {
+      surfaces: [
+        {
+          subpath: "./shared",
+          summary: "Exports Google rewarded shared CRUD resources."
+        },
+        {
+          subpath: "./server/actions",
+          summary: "Exports Google rewarded workflow action identifiers and validators."
+        },
+        {
+          subpath: "./server/requireGoogleRewardedUnlock",
+          summary: "Exports the server helper that enforces a rewarded unlock before a protected feature action continues."
+        }
+      ],
+      containerTokens: {
+        server: [
+          "repository.google_rewarded_rules",
+          "crud.google_rewarded_rules",
+          "repository.google_rewarded_provider_configs",
+          "crud.google_rewarded_provider_configs",
+          "repository.google_rewarded_watch_sessions",
+          "crud.google_rewarded_watch_sessions",
+          "repository.google_rewarded_unlock_receipts",
+          "crud.google_rewarded_unlock_receipts",
+          "google-rewarded.core.service"
+        ],
+        client: []
+      }
+    }
+  },
+  mutations: {
+    dependencies: {
+      runtime: {
+        "@jskit-ai/auth-core": "0.1.63",
+        "@jskit-ai/crud-core": "0.1.72",
+        "@jskit-ai/database-runtime": "0.1.64",
+        "@jskit-ai/http-runtime": "0.1.63",
+        "@jskit-ai/json-rest-api-core": "0.1.9",
+        "@jskit-ai/kernel": "0.1.64",
+        "@jskit-ai/resource-crud-core": "0.1.9",
+        "@jskit-ai/workspaces-core": "0.1.40"
+      },
+      dev: {}
+    },
+    packageJson: {
+      scripts: {}
+    },
+    procfile: {},
+    files: [
+      {
+        op: "install-migration",
+        from: "templates/migrations/google_rewarded_rules_initial.cjs",
+        toDir: "migrations",
+        extension: ".cjs",
+        reason: "Install Google rewarded rules schema migration.",
+        category: "google-rewarded",
+        id: "google-rewarded-rules-initial-schema"
+      },
+      {
+        op: "install-migration",
+        from: "templates/migrations/google_rewarded_provider_configs_initial.cjs",
+        toDir: "migrations",
+        extension: ".cjs",
+        reason: "Install Google rewarded provider config schema migration.",
+        category: "google-rewarded",
+        id: "google-rewarded-provider-configs-initial-schema"
+      },
+      {
+        op: "install-migration",
+        from: "templates/migrations/google_rewarded_watch_sessions_initial.cjs",
+        toDir: "migrations",
+        extension: ".cjs",
+        reason: "Install Google rewarded watch sessions schema migration.",
+        category: "google-rewarded",
+        id: "google-rewarded-watch-sessions-initial-schema"
+      },
+      {
+        op: "install-migration",
+        from: "templates/migrations/google_rewarded_unlock_receipts_initial.cjs",
+        toDir: "migrations",
+        extension: ".cjs",
+        reason: "Install Google rewarded unlock receipts schema migration.",
+        category: "google-rewarded",
+        id: "google-rewarded-unlock-receipts-initial-schema"
+      }
+    ],
+    text: []
+  }
+});

package/package.json

@@ -0,0 +1,10 @@
+{
+  "name": "@jskit-ai/google-rewarded-core",
+  "version": "0.1.1",
+  "type": "module",
+  "exports": {
+    "./shared": "./src/shared/index.js",
+    "./server/actions": "./src/server/actions.js",
+    "./server/requireGoogleRewardedUnlock": "./src/server/support/requireGoogleRewardedUnlock.js"
+  }
+}

package/src/server/GoogleRewardedCoreProvider.js

@@ -0,0 +1,51 @@
+import { withActionDefaults } from "@jskit-ai/kernel/shared/actions";
+
+import { createService } from "./service.js";
+import { googleRewardedActions } from "./actions.js";
+import { registerRoutes } from "./registerRoutes.js";
+
+class GoogleRewardedCoreProvider {
+  static id = "google-rewarded.core";
+
+  static dependsOn = ["runtime.actions"];
+
+  register(app) {
+    if (
+      !app ||
+      typeof app.singleton !== "function" ||
+      typeof app.service !== "function" ||
+      typeof app.actions !== "function"
+    ) {
+      throw new Error("GoogleRewardedCoreProvider requires application singleton()/service()/actions().");
+    }
+
+    app.service(
+      "google-rewarded.core.service",
+      (scope) => createService({
+        googleRewardedRulesRepository: scope.make("repository.google_rewarded_rules"),
+        googleRewardedProviderConfigsRepository: scope.make("repository.google_rewarded_provider_configs"),
+        googleRewardedWatchSessionsRepository: scope.make("repository.google_rewarded_watch_sessions"),
+        googleRewardedUnlockReceiptsRepository: scope.make("repository.google_rewarded_unlock_receipts")
+      })
+    );
+
+    app.actions(
+      withActionDefaults(googleRewardedActions, {
+        domain: "google-rewarded",
+        dependencies: {
+          googleRewardedService: "google-rewarded.core.service"
+        }
+      })
+    );
+  }
+
+  boot(app) {
+    registerRoutes(app, {
+      routeOwnershipFilter: "workspace_user",
+      routeSurface: "app",
+      routeRelativePath: "google-rewarded"
+    });
+  }
+}
+
+export { GoogleRewardedCoreProvider };

package/src/server/actions.js

@@ -0,0 +1,102 @@
+import {
+  currentQueryInputValidator,
+  startCommandInputValidator,
+  grantCommandInputValidator,
+  closeCommandInputValidator,
+  currentStateOutputValidator,
+  startGateOutputValidator,
+  grantRewardOutputValidator,
+  closeSessionOutputValidator
+} from "./inputSchemas.js";
+
+const ACTION_CURRENT = "google-rewarded.current.read";
+const ACTION_START = "google-rewarded.start";
+const ACTION_GRANT = "google-rewarded.grant";
+const ACTION_CLOSE = "google-rewarded.close";
+
+const googleRewardedActions = Object.freeze([
+  {
+    id: ACTION_CURRENT,
+    version: 1,
+    kind: "query",
+    channels: ["api", "automation", "internal"],
+    surfacesFrom: "enabled",
+    input: currentQueryInputValidator,
+    output: currentStateOutputValidator,
+    idempotency: "none",
+    audit: {
+      actionName: ACTION_CURRENT
+    },
+    observability: {},
+    async execute(input, context, deps) {
+      return deps.googleRewardedService.getCurrentState(input, {
+        context
+      });
+    }
+  },
+  {
+    id: ACTION_START,
+    version: 1,
+    kind: "command",
+    channels: ["api", "automation", "internal"],
+    surfacesFrom: "enabled",
+    input: startCommandInputValidator,
+    output: startGateOutputValidator,
+    idempotency: "optional",
+    audit: {
+      actionName: ACTION_START
+    },
+    observability: {},
+    async execute(input, context, deps) {
+      return deps.googleRewardedService.startGate(input, {
+        context
+      });
+    }
+  },
+  {
+    id: ACTION_GRANT,
+    version: 1,
+    kind: "command",
+    channels: ["api", "automation", "internal"],
+    surfacesFrom: "enabled",
+    input: grantCommandInputValidator,
+    output: grantRewardOutputValidator,
+    idempotency: "optional",
+    audit: {
+      actionName: ACTION_GRANT
+    },
+    observability: {},
+    async execute(input, context, deps) {
+      return deps.googleRewardedService.grantReward(input, {
+        context
+      });
+    }
+  },
+  {
+    id: ACTION_CLOSE,
+    version: 1,
+    kind: "command",
+    channels: ["api", "automation", "internal"],
+    surfacesFrom: "enabled",
+    input: closeCommandInputValidator,
+    output: closeSessionOutputValidator,
+    idempotency: "optional",
+    audit: {
+      actionName: ACTION_CLOSE
+    },
+    observability: {},
+    async execute(input, context, deps) {
+      return deps.googleRewardedService.closeSession(input, {
+        context
+      });
+    }
+  }
+]);
+
+export {
+  ACTION_CURRENT,
+  ACTION_START,
+  ACTION_GRANT,
+  ACTION_CLOSE,
+  googleRewardedActions
+};