@playruo/embed 1.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Playruo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,149 @@
+# @playruo/embed
+
+React SDK to embed Playruo via iframe + postMessage.
+
+See the official docs: [Playruo Embed Documentation](https://playruo.notion.site/Playruo-Embed-Documentation-268a5e7d674180dd901ae0753187d7c1?pvs=74).
+
+## Install
+
+```bash
+npm i @playruo/embed
+```
+
+## Quick start (Next.js / React)
+
+```tsx
+"use client";
+import { PlayruoEmbed } from "@playruo/embed";
+
+export const Demo = () => (
+  <PlayruoEmbed
+    operation="iframe"
+    storeUrl="https://store.steampowered.com/app/2751000/..."
+    showIframe
+    onReady={() => console.log("ready")}
+    onStateChange={(state) => console.log("state", state)}
+    onDemoCompleted={(data) => console.log("completed", data)}
+    onPurchaseRequest={({ storeUrl }) => {
+      // Example: open the store page in a new tab
+      window.open(storeUrl, "_blank", "noopener,noreferrer");
+    }}
+    onError={(message) => console.error(message)}
+  />
+);
+```
+
+## Headless mode (with renderState)
+
+```tsx
+import { PlayruoEmbed } from "@playruo/embed";
+
+<PlayruoEmbed
+  // operation is optional, defaults to "iframe"
+  storeUrl="https://store.steampowered.com/app/2751000/..."
+  showIframe
+  renderState={({ status, message }) => {
+    if (status === "loading") return <div>Loading demo…</div>;
+    if (status === "error") return <div>Error: {message}</div>;
+    if (status === "available")
+      return (
+        <div className="flex gap-3">
+          <button>Try Now</button>
+        </div>
+      );
+    // unavailable
+    return (
+      <div className="flex gap-3">
+        <span>{message ?? "Unavailable"}</span>
+        <button>Buy Now</button>
+      </div>
+    );
+  }}
+/>
+```
+
+### Props
+
+- **operation**: string (optional, default: "iframe")
+- **storeUrl**: string (optional)
+- **showIframe**: boolean (optional)
+- **className**: string (optional)
+- **onReady()**: callback when the iframe signals readiness
+- **onStateChange(state)**: receives live availability state
+- **onDemoCompleted(data)**: fired when the demo session completes
+- **onPurchaseRequest({ storeUrl })**: fired when purchase is requested
+- **onError(message)**: fired on error
+
+#### Render API
+
+- **renderState({ status, message })**: single render entry point
+  - `status`: "loading" | "available" | "unavailable" | "error"
+  - `message?`: optional status message (e.g. availability reason)
+
+
+### Events
+
+- **onReady()**
+- **onStateChange(state)**
+- **onDemoCompleted(data)**
+- **onPurchaseRequest({ storeUrl })**
+- **onError(error)**
+
+## State shape
+
+```ts
+export interface PlayruoEmbedState {
+  hasPlayedOnce: boolean;
+  tryNow: { available: boolean; status?: string };
+  buyNow: { available: boolean; status?: string };
+}
+```
+
+## Commands (postMessage)
+
+The component exposes two imperative actions via the render API:
+
+- `tryNow()` → posts `"try_now"` to the iframe
+- `buyNow()` → posts `"buy_now"` to the iframe
+
+## Incoming messages (from iframe)
+
+The component listens to Playruo postMessage events and triggers the corresponding callbacks:
+
+- `"playruo:ready"` (also accepts legacy `"playruo_ready"`) → `onReady()`
+- `"playruo:state"` (also accepts legacy `"playruo_state_update"`) → `onStateChange(state)`
+- `"playruo:demoCompleted"` (also accepts legacy `"playruo_demo_completed"`) → `onDemoCompleted(data)`
+- `"playruo:purchaseRequest"` (also accepts legacy `"playruo_purchase_request"`) → `onPurchaseRequest({ storeUrl })`
+- `"playruo:error"` (also accepts legacy `"playruo_error"`) → `onError(message)`
+
+## URL builder
+
+You can build the iframe URL manually if needed:
+
+```ts
+import { buildEmbedUrl } from "@playruo/embed";
+
+const url = buildEmbedUrl({
+  operation: "iframe", // default
+  storeUrl: "https://store.steampowered.com/app/2751000/...", // optional
+});
+``;
+
+The URL points to `"/embed"` and accepts the query params:
+
+- `operation` (string, default: `"iframe"`)
+- `storeUrl` (string, optional)
+
+## Iframe behavior
+
+- The iframe is always present in the DOM. Set `showIframe` to control visibility.
+- The iframe has `allow="fullscreen *; autoplay *; gamepad *"`.
+
+## Types
+
+Named exports:
+
+- `PlayruoEmbed`
+- `buildEmbedUrl`
+- `PlayruoEmbedState`
+- `PlayruoEmbedMessage<T>`

package/dist/index.cjs

@@ -0,0 +1,116 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  PlayruoEmbed: () => PlayruoEmbed,
+  buildEmbedUrl: () => buildEmbedUrl
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/react/playruo-embed.tsx
+var import_react = require("react");
+
+// src/url.ts
+var buildEmbedUrl = ({ baseUrl, operation = "iframe", storeUrl }) => {
+  const url = new URL("/embed", baseUrl);
+  url.searchParams.set("operation", operation);
+  if (storeUrl) url.searchParams.set("storeUrl", storeUrl);
+  return url.toString();
+};
+
+// src/react/playruo-embed.tsx
+var import_jsx_runtime = require("react/jsx-runtime");
+var PlayruoEmbed = ({
+  baseUrl,
+  operation = "iframe",
+  storeUrl,
+  showIframe = false,
+  className,
+  onReady,
+  onStateChange,
+  onDemoCompleted,
+  onPurchaseRequest,
+  onError,
+  renderState
+}) => {
+  const iframeRef = (0, import_react.useRef)(null);
+  const [isReady, setIsReady] = (0, import_react.useState)(false);
+  const [state, setState] = (0, import_react.useState)(null);
+  const [errorMessage, setErrorMessage] = (0, import_react.useState)(null);
+  const src = (0, import_react.useMemo)(() => buildEmbedUrl({ baseUrl, operation, storeUrl }), [baseUrl, operation, storeUrl]);
+  (0, import_react.useEffect)(() => {
+    const handler = (event) => {
+      const msg = event?.data ?? {};
+      if (!msg || typeof msg.type !== "string" || !msg.type.startsWith("playruo")) return;
+      if (msg.type === "playruo:ready" || msg.type === "playruo_ready") {
+        setIsReady(true);
+        onReady?.();
+      } else if (msg.type === "playruo:state" || msg.type === "playruo_state_update") {
+        setState(msg.data);
+        onStateChange?.(msg.data);
+      } else if (msg.type === "playruo:demoCompleted" || msg.type === "playruo_demo_completed") {
+        onDemoCompleted?.(msg.data);
+      } else if (msg.type === "playruo:purchaseRequest" || msg.type === "playruo_purchase_request") {
+        onPurchaseRequest?.(msg.data);
+      } else if (msg.type === "playruo:error" || msg.type === "playruo_error") {
+        const message = msg.data?.message ?? "Unknown error";
+        setErrorMessage(message);
+        onError?.(message);
+      }
+    };
+    window.addEventListener("message", handler);
+    return () => window.removeEventListener("message", handler);
+  }, [onReady, onStateChange, onDemoCompleted, onPurchaseRequest, onError]);
+  const isAvailable = Boolean(isReady && state?.tryNow?.available);
+  const renderContent = () => {
+    if (!renderState) return null;
+    if (errorMessage) return renderState({ status: "error", message: errorMessage });
+    if (!isReady) return renderState({ status: "loading" });
+    const message = !isAvailable ? state?.tryNow?.status ?? state?.buyNow?.status : void 0;
+    return renderState({ status: isAvailable ? "available" : "unavailable", message });
+  };
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", { className, children: [
+    renderContent(),
+    /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+      "iframe",
+      {
+        ref: iframeRef,
+        src,
+        allow: "fullscreen *; autoplay *; gamepad *",
+        className: "w-full h-[70vh] rounded-lg border",
+        title: "Playruo",
+        style: {
+          position: showIframe ? void 0 : "absolute",
+          top: showIframe ? void 0 : -9999,
+          left: showIframe ? void 0 : -9999,
+          zIndex: showIframe ? void 0 : -10,
+          opacity: showIframe ? 1 : 0,
+          pointerEvents: showIframe ? "auto" : "none"
+        }
+      }
+    )
+  ] });
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  PlayruoEmbed,
+  buildEmbedUrl
+});

package/dist/index.d.cts

@@ -0,0 +1,53 @@
+import { FC, ReactNode } from 'react';
+
+interface PlayruoEmbedState {
+    hasPlayedOnce: boolean;
+    tryNow: {
+        available: boolean;
+        status?: string;
+    };
+    buyNow: {
+        available: boolean;
+        status?: string;
+    };
+}
+interface PlayruoEmbedMessage<T = unknown> {
+    type: `playruo:${string}`;
+    data?: T;
+}
+interface DemoCompletedPayload {
+    reason?: string;
+    storeUrl?: string;
+}
+
+interface PlayruoEmbedProps {
+    baseUrl: string;
+    operation?: string;
+    storeUrl?: string;
+    showIframe?: boolean;
+    className?: string;
+    onReady?: () => void;
+    onStateChange?: (state: PlayruoEmbedState) => void;
+    onDemoCompleted?: (data: DemoCompletedPayload) => void;
+    onPurchaseRequest?: (data: {
+        storeUrl: string;
+    }) => void;
+    onError?: (error: string) => void;
+    /**
+     * Single render entry point representing the current status.
+     */
+    renderState?: (render: {
+        status: "loading" | "available" | "unavailable" | "error";
+        message?: string;
+    }) => ReactNode;
+}
+declare const PlayruoEmbed: FC<PlayruoEmbedProps>;
+
+interface BuildUrlParams {
+    baseUrl: string;
+    operation?: string;
+    storeUrl?: string;
+}
+declare const buildEmbedUrl: ({ baseUrl, operation, storeUrl }: BuildUrlParams) => string;
+
+export { PlayruoEmbed, type PlayruoEmbedMessage, type PlayruoEmbedState, buildEmbedUrl };

package/dist/index.d.ts

@@ -0,0 +1,53 @@
+import { FC, ReactNode } from 'react';
+
+interface PlayruoEmbedState {
+    hasPlayedOnce: boolean;
+    tryNow: {
+        available: boolean;
+        status?: string;
+    };
+    buyNow: {
+        available: boolean;
+        status?: string;
+    };
+}
+interface PlayruoEmbedMessage<T = unknown> {
+    type: `playruo:${string}`;
+    data?: T;
+}
+interface DemoCompletedPayload {
+    reason?: string;
+    storeUrl?: string;
+}
+
+interface PlayruoEmbedProps {
+    baseUrl: string;
+    operation?: string;
+    storeUrl?: string;
+    showIframe?: boolean;
+    className?: string;
+    onReady?: () => void;
+    onStateChange?: (state: PlayruoEmbedState) => void;
+    onDemoCompleted?: (data: DemoCompletedPayload) => void;
+    onPurchaseRequest?: (data: {
+        storeUrl: string;
+    }) => void;
+    onError?: (error: string) => void;
+    /**
+     * Single render entry point representing the current status.
+     */
+    renderState?: (render: {
+        status: "loading" | "available" | "unavailable" | "error";
+        message?: string;
+    }) => ReactNode;
+}
+declare const PlayruoEmbed: FC<PlayruoEmbedProps>;
+
+interface BuildUrlParams {
+    baseUrl: string;
+    operation?: string;
+    storeUrl?: string;
+}
+declare const buildEmbedUrl: ({ baseUrl, operation, storeUrl }: BuildUrlParams) => string;
+
+export { PlayruoEmbed, type PlayruoEmbedMessage, type PlayruoEmbedState, buildEmbedUrl };

package/dist/index.js

@@ -0,0 +1,88 @@
+// src/react/playruo-embed.tsx
+import { useEffect, useMemo, useRef, useState } from "react";
+
+// src/url.ts
+var buildEmbedUrl = ({ baseUrl, operation = "iframe", storeUrl }) => {
+  const url = new URL("/embed", baseUrl);
+  url.searchParams.set("operation", operation);
+  if (storeUrl) url.searchParams.set("storeUrl", storeUrl);
+  return url.toString();
+};
+
+// src/react/playruo-embed.tsx
+import { jsx, jsxs } from "react/jsx-runtime";
+var PlayruoEmbed = ({
+  baseUrl,
+  operation = "iframe",
+  storeUrl,
+  showIframe = false,
+  className,
+  onReady,
+  onStateChange,
+  onDemoCompleted,
+  onPurchaseRequest,
+  onError,
+  renderState
+}) => {
+  const iframeRef = useRef(null);
+  const [isReady, setIsReady] = useState(false);
+  const [state, setState] = useState(null);
+  const [errorMessage, setErrorMessage] = useState(null);
+  const src = useMemo(() => buildEmbedUrl({ baseUrl, operation, storeUrl }), [baseUrl, operation, storeUrl]);
+  useEffect(() => {
+    const handler = (event) => {
+      const msg = event?.data ?? {};
+      if (!msg || typeof msg.type !== "string" || !msg.type.startsWith("playruo")) return;
+      if (msg.type === "playruo:ready" || msg.type === "playruo_ready") {
+        setIsReady(true);
+        onReady?.();
+      } else if (msg.type === "playruo:state" || msg.type === "playruo_state_update") {
+        setState(msg.data);
+        onStateChange?.(msg.data);
+      } else if (msg.type === "playruo:demoCompleted" || msg.type === "playruo_demo_completed") {
+        onDemoCompleted?.(msg.data);
+      } else if (msg.type === "playruo:purchaseRequest" || msg.type === "playruo_purchase_request") {
+        onPurchaseRequest?.(msg.data);
+      } else if (msg.type === "playruo:error" || msg.type === "playruo_error") {
+        const message = msg.data?.message ?? "Unknown error";
+        setErrorMessage(message);
+        onError?.(message);
+      }
+    };
+    window.addEventListener("message", handler);
+    return () => window.removeEventListener("message", handler);
+  }, [onReady, onStateChange, onDemoCompleted, onPurchaseRequest, onError]);
+  const isAvailable = Boolean(isReady && state?.tryNow?.available);
+  const renderContent = () => {
+    if (!renderState) return null;
+    if (errorMessage) return renderState({ status: "error", message: errorMessage });
+    if (!isReady) return renderState({ status: "loading" });
+    const message = !isAvailable ? state?.tryNow?.status ?? state?.buyNow?.status : void 0;
+    return renderState({ status: isAvailable ? "available" : "unavailable", message });
+  };
+  return /* @__PURE__ */ jsxs("div", { className, children: [
+    renderContent(),
+    /* @__PURE__ */ jsx(
+      "iframe",
+      {
+        ref: iframeRef,
+        src,
+        allow: "fullscreen *; autoplay *; gamepad *",
+        className: "w-full h-[70vh] rounded-lg border",
+        title: "Playruo",
+        style: {
+          position: showIframe ? void 0 : "absolute",
+          top: showIframe ? void 0 : -9999,
+          left: showIframe ? void 0 : -9999,
+          zIndex: showIframe ? void 0 : -10,
+          opacity: showIframe ? 1 : 0,
+          pointerEvents: showIframe ? "auto" : "none"
+        }
+      }
+    )
+  ] });
+};
+export {
+  PlayruoEmbed,
+  buildEmbedUrl
+};

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@playruo/embed",
+  "version": "1.1.1",
+  "description": "React SDK to embed Playruo with postMessage API.",
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/index.cjs",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": ["dist"],
+  "sideEffects": false,
+  "peerDependencies": {
+    "react": ">=18",
+    "react-dom": ">=18"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.4.0",
+    "@types/react": "^19",
+    "@types/react-dom": "^19"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts --clean",
+    "dev": "tsup src/index.ts --format esm --dts --watch",
+    "prepare": "npm run build"
+  }
+}