@jskit-ai/rewarded-web 0.1.120

package/README.md

@@ -0,0 +1,44 @@
+# @jskit-ai/rewarded-web
+
+Client workflow and gate UI for application-owned rewards. The package requires
+`client.vue` and an explicit `client.rewarded-delivery` capability. Installing it
+does not load an ad SDK or select a provider.
+
+## Application use
+
+```js
+const rewarded = useRewardedRuntime();
+const result = await rewarded.requireUnlock({ gateKey: "bonus", workspaceSlug });
+```
+
+The workflow opens a prompt before delivery. It handles existing unlocks, grants,
+closed sessions and unavailable delivery through the app's `/rewarded/*` routes.
+The delivery capability supplies `launchReward({ providerConfig, onReady,
+onGranted, onClosed, onUnavailable })`, returning a promise for its lifecycle.
+Provider configuration is opaque to the workflow. The application authorizes
+server grants; browser callbacks alone do not prove provider viewing.
+
+The existing gate is app-surface-only. The installed provider mounts its host
+and supplies `client.rewarded`; direct callers use `createRewardedRuntime({
+launchReward })`. Missing delivery fails rather than selecting Google.
+
+## Google delivery pattern
+
+See [Google rewarded delivery](patterns/google-rewarded/PATTERN.md). Copy the
+adapter and provider into the application and register its provider alongside
+`RewardedClientProvider`. The example handles Publisher Tag script loading,
+rewarded events and slot cleanup. It accepts provider `google-publisher-tag` and
+uses the configured placement as the Google ad unit path.
+
+## V0 migration
+
+Replace old package imports, `GoogleRewarded*` symbols and `google-rewarded.*`
+capabilities with the generic names. Replace `useGoogleRewardedRuntime()` with
+`useRewardedRuntime()` and supply delivery explicitly for direct construction.
+There is no compatibility fallback. The core README describes table, route and
+configuration migration. Install `@jskit-ai/rewarded-core` for server workflow
+ownership; the Google example remains application source.
+
+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/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@jskit-ai/rewarded-web",
+  "version": "0.1.120",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.js",
+    "./client": "./src/client/index.js",
+    "./server": "./src/server/index.js",
+    "./shared": "./src/shared/index.js"
+  },
+  "description": "Rewarded gate client workflow with explicitly composed application delivery.",
+  "jskit": {
+    "kind": "runtime",
+    "capabilities": {
+      "provides": [
+        "rewarded.web"
+      ],
+      "requires": [
+        "client.vue",
+        "client.rewarded-delivery"
+      ],
+      "applicationRequires": [
+        "client.rewarded-delivery"
+      ]
+    },
+    "runtime": {
+      "server": {
+        "providers": []
+      },
+      "client": {
+        "providers": [
+          {
+            "entrypoint": "src/client/providers/RewardedClientProvider.js",
+            "export": "RewardedClientProvider"
+          }
+        ]
+      }
+    },
+    "metadata": {
+      "apiSummary": {
+        "surfaces": [
+          {
+            "subpath": "./client",
+            "summary": "Exports the Rewarded client provider, runtime composable, and fullscreen gate host."
+          }
+        ]
+      },
+      "client": {
+        "singleton": true
+      }
+    }
+  },
+  "dependencies": {
+    "@jskit-ai/rewarded-core": "0.1.120"
+  },
+  "peerDependencies": {
+    "@jskit-ai/http-runtime": "0.1.182",
+    "@jskit-ai/kernel": "0.1.184",
+    "@jskit-ai/shell-web": "0.1.188"
+  }
+}

package/patterns/google-rewarded/PATTERN.md

@@ -0,0 +1,69 @@
+---
+id: rewards/google-rewarded
+title: Google rewarded delivery
+summary: Compose application-owned Google Publisher Tag delivery with the generic rewarded workflow.
+keywords: rewarded, google, publisher tag, ads, unlock
+requires: @jskit-ai/rewarded-web
+---
+
+# Google rewarded delivery
+
+## Use when
+
+The application owner has selected Google rewarded ads and configured its
+publisher account and ad unit.
+
+## Do not use when
+
+The application needs a Google Ads API connection, application login, or an
+independent server proof of ad viewing.
+
+## Product decisions
+
+Choose the rewarded feature, user eligibility, publisher account, placement,
+consent experience and server grant policy. The app owns these decisions.
+
+## Invariants
+
+- Generic workflow code does not choose a delivery provider.
+- The app explicitly provides `client.rewarded-delivery`.
+- Browser reward events are not independent server verification of viewing.
+- The adapter removes listeners and slots when settled.
+
+## Framework APIs
+
+Register `GoogleRewardedDeliveryProvider` in ordinary application client
+capability composition beside `RewardedClientProvider` from
+`@jskit-ai/rewarded-web/client`. The example supplies
+`client.rewarded-delivery`; the generic UI supplies `client.rewarded`.
+Use `useRewardedRuntime().requireUnlock({ gateKey, workspaceSlug })` for gates.
+Separately supply server capability `rewarded.grant-policy` with
+`authorizeGrant({ session, context, trx })`; only `true` permits a grant.
+This delivery example does not provide or choose the server policy.
+
+## Example files
+
+Copy `example/googlePublisherTag.js` and
+`example/GoogleRewardedDeliveryProvider.js` into application source. The adapter
+loads Publisher Tag after the user starts the reward flow and maps
+ready/granted/closed events to workflow callbacks.
+
+## Variation points
+
+Configure the app's reward provider row with `provider: "google-publisher-tag"`
+and `placement` equal to its ad unit path. Choose gate limits and duration through
+the core workflow's rule configuration. Use a different delivery provider for
+other services; do not add implicit fallback inside the generic runtime.
+
+## Verification
+
+Use controlled SDK events to verify grant, close, unavailable slot and cleanup.
+Test server authorization and isolation with the application's own user context.
+Check duplicate grant and expired unlock behavior before enabling the feature.
+
+## Avoid
+
+- claiming browser events prove provider viewing to the server
+- enabling Google delivery without an explicit application choice
+- adding API credentials or provider registrations to generic workflow code
+- treating an Ads API connector as rewarded browser delivery

package/patterns/google-rewarded/example/GoogleRewardedDeliveryProvider.js

@@ -0,0 +1,12 @@
+import { defineProvider } from "@jskit-ai/kernel/shared/capabilities";
+import { launchGoogleRewardedAd } from "./googlePublisherTag.js";
+
+const GoogleRewardedDeliveryProvider = defineProvider({
+  id: "app.rewarded.google",
+  provides: { delivery: "client.rewarded-delivery" },
+  setup() {
+    return { delivery: { launchReward: launchGoogleRewardedAd } };
+  }
+});
+
+export { GoogleRewardedDeliveryProvider };

package/patterns/google-rewarded/example/googlePublisherTag.js

@@ -0,0 +1,142 @@
+let gptLoadPromise = null;
+let gptServicesEnabled = false;
+
+async function ensureGooglePublisherTagLoaded() {
+  if (typeof window === "undefined" || typeof document === "undefined") {
+    throw new Error("Rewarded runtime requires a browser environment.");
+  }
+
+  if (window.googletag?.apiReady === true) {
+    return window.googletag;
+  }
+  if (gptLoadPromise) {
+    return gptLoadPromise;
+  }
+
+  window.googletag ||= { cmd: [] };
+  gptLoadPromise = new Promise((resolve, reject) => {
+    const existingScript = document.querySelector('script[data-jskit-rewarded-gpt="true"]');
+    if (existingScript) {
+      existingScript.addEventListener("load", () => resolve(window.googletag), { once: true });
+      existingScript.addEventListener("error", () => reject(new Error("Failed to load Google Publisher Tag.")), { once: true });
+      return;
+    }
+
+    const script = document.createElement("script");
+    script.async = true;
+    script.src = "https://securepubads.g.doubleclick.net/tag/js/gpt.js";
+    script.dataset.jskitRewardedGpt = "true";
+    script.addEventListener("load", () => resolve(window.googletag), { once: true });
+    script.addEventListener("error", () => reject(new Error("Failed to load Google Publisher Tag.")), { once: true });
+    document.head.appendChild(script);
+  }).catch((error) => {
+    gptLoadPromise = null;
+    throw error;
+  });
+
+  return gptLoadPromise;
+}
+
+function launchGoogleRewardedAd({
+  providerConfig,
+  onReady = null,
+  onGranted = null,
+  onClosed = null,
+  onUnavailable = null
+} = {}) {
+  if (providerConfig?.provider !== "google-publisher-tag") {
+    throw new TypeError("Google delivery requires provider google-publisher-tag.");
+  }
+  const placement = String(providerConfig?.placement || "").trim();
+  if (!placement) throw new TypeError("Rewarded delivery requires placement.");
+  return ensureGooglePublisherTagLoaded().then((googletag) =>
+    new Promise((resolve, reject) => {
+      googletag.cmd.push(() => {
+        const pubads = googletag.pubads();
+        const rewardedFormat = googletag?.enums?.OutOfPageFormat?.REWARDED;
+        if (!rewardedFormat) {
+          reject(new Error("Rewarded ads are not supported by this GPT build."));
+          return;
+        }
+
+        const slot = googletag.defineOutOfPageSlot(placement, rewardedFormat);
+        if (!slot) {
+          Promise.resolve(onUnavailable?.()).finally(() => {
+            reject(new Error("Rewarded ads are not available on this page."));
+          });
+          return;
+        }
+
+        let readySeen = false;
+        let settled = false;
+
+        const cleanup = () => {
+          if (typeof pubads.removeEventListener === "function") {
+            pubads.removeEventListener("rewardedSlotReady", handleReady);
+            pubads.removeEventListener("rewardedSlotGranted", handleGranted);
+            pubads.removeEventListener("rewardedSlotClosed", handleClosed);
+          }
+          if (typeof googletag.destroySlots === "function") {
+            googletag.destroySlots([slot]);
+          }
+        };
+
+        const handleReady = async (event) => {
+          if (event?.slot !== slot || settled) {
+            return;
+          }
+          readySeen = true;
+          await Promise.resolve(onReady?.());
+          if (typeof event.makeRewardedVisible === "function") {
+            event.makeRewardedVisible();
+          }
+        };
+
+        const handleGranted = async (event) => {
+          if (event?.slot !== slot || settled) {
+            return;
+          }
+          await Promise.resolve(onGranted?.());
+        };
+
+        const handleClosed = async (event) => {
+          if (event?.slot !== slot || settled) {
+            return;
+          }
+          settled = true;
+          cleanup();
+          try {
+            await Promise.resolve(onClosed?.());
+            resolve();
+          } catch (error) {
+            reject(error);
+          }
+        };
+
+        pubads.addEventListener("rewardedSlotReady", handleReady);
+        pubads.addEventListener("rewardedSlotGranted", handleGranted);
+        pubads.addEventListener("rewardedSlotClosed", handleClosed);
+        slot.addService(pubads);
+
+        if (!gptServicesEnabled) {
+          googletag.enableServices();
+          gptServicesEnabled = true;
+        }
+
+        googletag.display(slot);
+        window.setTimeout(() => {
+          if (settled || readySeen) {
+            return;
+          }
+          settled = true;
+          cleanup();
+          Promise.resolve(onUnavailable?.()).finally(() => {
+            reject(new Error("No rewarded ad was available."));
+          });
+        }, 10000);
+      });
+    })
+  );
+}
+
+export { launchGoogleRewardedAd };

package/src/client/components/RewardedGateHost.vue

@@ -0,0 +1,184 @@
+<script setup>
+import { computed } from "vue";
+import { useRewardedRuntime } from "../composables/useRewardedRuntime.js";
+
+const props = defineProps({
+  runtime: {
+    type: Object,
+    required: false,
+    default: null
+  }
+});
+
+const runtime = computed(() => props.runtime || useRewardedRuntime());
+const state = computed(() => runtime.value?.state || null);
+const isVisible = computed(() => {
+  const currentState = state.value;
+  return currentState?.open === true && currentState?.phase !== "showing-ad";
+});
+const titleText = computed(() => state.value?.gateState?.rule?.title || "Watch an ad to continue");
+const descriptionText = computed(() =>
+  state.value?.gateState?.rule?.description ||
+  "Watch a rewarded ad to unlock this action."
+);
+
+function handleWatchClick() {
+  runtime.value?.beginWatch?.();
+}
+
+function handleCancelClick() {
+  runtime.value?.cancelPrompt?.();
+}
+
+function handleDismissError() {
+  runtime.value?.dismissError?.();
+}
+</script>
+
+<template>
+  <Teleport to="body">
+    <div v-if="isVisible" class="rewarded-gate">
+      <div class="rewarded-gate__scrim" />
+      <div class="rewarded-gate__panel">
+        <div class="rewarded-gate__eyebrow">Rewarded unlock</div>
+        <h2 class="rewarded-gate__title">{{ titleText }}</h2>
+        <p class="rewarded-gate__description">{{ descriptionText }}</p>
+
+        <p
+          v-if="state?.phase === 'loading'"
+          class="rewarded-gate__status"
+        >
+          Loading Rewarded ad…
+        </p>
+
+        <p
+          v-else-if="state?.phase === 'error'"
+          class="rewarded-gate__status rewarded-gate__status--error"
+        >
+          {{ state?.errorMessage || "Unable to start the rewarded ad." }}
+        </p>
+
+        <div class="rewarded-gate__actions">
+          <button
+            v-if="state?.phase === 'prompt'"
+            type="button"
+            class="rewarded-gate__button rewarded-gate__button--primary"
+            @click="handleWatchClick"
+          >
+            Watch ad
+          </button>
+
+          <button
+            v-if="state?.phase === 'prompt'"
+            type="button"
+            class="rewarded-gate__button"
+            @click="handleCancelClick"
+          >
+            Not now
+          </button>
+
+          <button
+            v-if="state?.phase === 'error'"
+            type="button"
+            class="rewarded-gate__button rewarded-gate__button--primary"
+            @click="handleDismissError"
+          >
+            Close
+          </button>
+        </div>
+      </div>
+    </div>
+  </Teleport>
+</template>
+
+<style scoped>
+.rewarded-gate {
+  position: fixed;
+  inset: 0;
+  z-index: 2147483000;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}
+
+.rewarded-gate__scrim {
+  position: absolute;
+  inset: 0;
+  background:
+    linear-gradient(180deg, rgba(15, 23, 42, 0.82), rgba(2, 6, 23, 0.94));
+  backdrop-filter: blur(4px);
+}
+
+.rewarded-gate__panel {
+  position: relative;
+  width: min(32rem, calc(100vw - 2rem));
+  border-radius: 1.5rem;
+  padding: 1.5rem;
+  background: #fffaf0;
+  color: #201510;
+  box-shadow: 0 2rem 5rem rgba(15, 23, 42, 0.35);
+}
+
+.rewarded-gate__eyebrow {
+  font-size: 0.75rem;
+  font-weight: 700;
+  letter-spacing: 0.12em;
+  text-transform: uppercase;
+  color: #9a3412;
+}
+
+.rewarded-gate__title {
+  margin: 0.5rem 0 0;
+  font-size: 1.5rem;
+  line-height: 1.2;
+}
+
+.rewarded-gate__description {
+  margin: 0.75rem 0 0;
+  line-height: 1.5;
+  color: #5b4636;
+}
+
+.rewarded-gate__status {
+  margin: 1rem 0 0;
+  font-size: 0.95rem;
+  color: #854d0e;
+}
+
+.rewarded-gate__status--error {
+  color: #991b1b;
+}
+
+.rewarded-gate__actions {
+  display: flex;
+  gap: 0.75rem;
+  margin-top: 1.25rem;
+}
+
+.rewarded-gate__button {
+  appearance: none;
+  border: 1px solid #d6d3d1;
+  border-radius: 999px;
+  padding: 0.8rem 1.2rem;
+  background: #fff;
+  color: inherit;
+  font: inherit;
+  cursor: pointer;
+}
+
+.rewarded-gate__button--primary {
+  border-color: transparent;
+  background: #ea580c;
+  color: #fff;
+}
+
+@media (max-width: 640px) {
+  .rewarded-gate__actions {
+    flex-direction: column;
+  }
+
+  .rewarded-gate__button {
+    width: 100%;
+  }
+}
+</style>

package/src/client/composables/useRewardedRuntime.js

@@ -0,0 +1,8 @@
+import { inject } from "vue";
+import { REWARDED_RUNTIME_INJECTION_KEY } from "../runtime/rewardedRuntime.js";
+
+function useRewardedRuntime() {
+  return inject(REWARDED_RUNTIME_INJECTION_KEY, null);
+}
+
+export { useRewardedRuntime };

package/src/client/index.js

@@ -0,0 +1,7 @@
+export { RewardedClientProvider } from "./providers/RewardedClientProvider.js";
+export { default as RewardedGateHost } from "./components/RewardedGateHost.vue";
+export {
+  REWARDED_RUNTIME_INJECTION_KEY,
+  createRewardedRuntime
+} from "./runtime/rewardedRuntime.js";
+export { useRewardedRuntime } from "./composables/useRewardedRuntime.js";

package/src/client/providers/RewardedClientProvider.js

@@ -0,0 +1,60 @@
+import { defineProvider } from "@jskit-ai/kernel/shared/capabilities";
+import { h, render } from "vue";
+import RewardedGateHost from "../components/RewardedGateHost.vue";
+import {
+  REWARDED_RUNTIME_INJECTION_KEY,
+  createRewardedRuntime
+} from "../runtime/rewardedRuntime.js";
+
+
+const mountedHosts = new WeakMap();
+
+const RewardedClientProvider = defineProvider({
+  id: "rewarded.web.client",
+  requires: {
+    vueApp: "client.vue",
+    delivery: "client.rewarded-delivery"
+  },
+  provides: {
+    rewarded: "client.rewarded"
+  },
+  setup({ delivery }) {
+    return {
+      rewarded: createRewardedRuntime({ launchReward: delivery.launchReward })
+    };
+  },
+  async boot({ vueApp }, { outputs }) {
+    if (typeof document === "undefined") {
+      return;
+    }
+
+    const runtime = outputs.rewarded;
+
+    if (vueApp && typeof vueApp.provide === "function") {
+      vueApp.provide(REWARDED_RUNTIME_INJECTION_KEY, runtime);
+    }
+
+    const hostContainer = document.createElement("div");
+    hostContainer.dataset.jskitRewardedHost = "true";
+    document.body.appendChild(hostContainer);
+
+    const vnode = h(RewardedGateHost, {
+      runtime
+    });
+    vnode.appContext = vueApp?._context || null;
+    render(vnode, hostContainer);
+    mountedHosts.set(runtime, hostContainer);
+  },
+  shutdown(_dependencies, { outputs }) {
+    const hostContainer = mountedHosts.get(outputs.rewarded);
+    if (!hostContainer) {
+      return;
+    }
+
+    render(null, hostContainer);
+    hostContainer.remove();
+    mountedHosts.delete(outputs.rewarded);
+  }
+});
+
+export { RewardedClientProvider };