@playruo/embed 1.1.2 → 1.1.3

package/README.md

@@ -36,30 +36,60 @@ export const Demo = () => (
 ## Headless mode (with renderState)
 
 ```tsx
+"use client";
 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>
-    );
-  }}
-/>
+import { useState } from "react";
+
+export const Demo = () => {
+  const [showIframe, setShowIframe] = useState(false);
+  
+  return (
+    <PlayruoEmbed
+      operation="iframe"
+      storeUrl="https://store.steampowered.com/app/2751000/..."
+      showIframe={showIframe}
+      renderState={({ status, message, actions }) => {
+        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 
+                onClick={() => {
+                  setShowIframe(true);
+                  actions.tryNow();
+                }}
+                disabled={!actions.canTryNow}
+              >
+                Try Now
+              </button>
+              <button 
+                onClick={actions.buyNow}
+                disabled={!actions.canBuyNow}
+              >
+                Buy Now
+              </button>
+            </div>
+          );
+        }
+        
+        // unavailable
+        return (
+          <div className="flex gap-3">
+            <span>{message ?? "Unavailable"}</span>
+            <button 
+              onClick={actions.buyNow}
+              disabled={!actions.canBuyNow}
+            >
+              Buy Now
+            </button>
+          </div>
+        );
+      }}
+    />
+  );
+};
 ```
 
 ### Props
@@ -76,9 +106,10 @@ import { PlayruoEmbed } from "@playruo/embed";
 
 #### Render API
 
-- **renderState({ status, message })**: single render entry point
+- **renderState({ status, message, actions })**: single render entry point
   - `status`: "loading" | "available" | "unavailable" | "error"
   - `message?`: optional status message (e.g. availability reason)
+  - `actions`: object with `tryNow()`, `buyNow()`, `canTryNow`, `canBuyNow`
 
 
 ### Events
@@ -99,51 +130,173 @@ export interface PlayruoEmbedState {
 }
 ```
 
-## Commands (postMessage)
+## Actions API
+
+The `renderState` callback receives an `actions` object with:
 
-The component exposes two imperative actions via the render API:
+- **`actions.tryNow()`** → sends `try_now` command to the iframe
+- **`actions.buyNow()`** → sends `buy_now` command to the iframe
+- **`actions.canTryNow`** → boolean indicating if try now is available
+- **`actions.canBuyNow`** → boolean indicating if buy now is available
 
-- `tryNow()` → posts `"try_now"` to the iframe
-- `buyNow()` → posts `"buy_now"` to the iframe
+```tsx
+renderState={({ actions }) => (
+  <button onClick={actions.tryNow} disabled={!actions.canTryNow}>
+    Try Now
+  </button>
+)}
+```
 
 ## 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)`
+- `"playruo_ready"` → `onReady()`
+- `"playruo_state_update"` → `onStateChange(state)`
+- `"playruo_demo_completed"` → `onDemoCompleted(data)`
+- `"playruo_purchase_request"` → `onPurchaseRequest({ storeUrl })`
+- `"playruo_error"` → `onError(message)`
 
-## URL builder
+## URL builder (Advanced)
 
-You can build the iframe URL manually if needed:
+For advanced use cases, you can build the iframe URL manually:
 
 ```ts
 import { buildEmbedUrl } from "@playruo/embed";
 
 const url = buildEmbedUrl({
-  operation: "iframe", // default
+  baseUrl: "https://playruo.example.com",
+  operation: "iframe", // optional, default: "iframe"
   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)
+The URL points to `{baseUrl}/embed` with query params:
+- `operation` (optional)
+- `storeUrl` (optional)
 
 ## Iframe behavior
 
 - The iframe is always present in the DOM. Set `showIframe` to control visibility.
 - The iframe has `allow="fullscreen *; autoplay *; gamepad *"`.
 
-## Types
+## TypeScript Types
+
+### Component Types
+
+```typescript
+import type {
+  PlayruoEmbedProps,
+  PlayruoEmbedState,
+  PlayruoEmbedActions,
+  PlayruoEmbedRenderState,
+  DemoCompletedPayload,
+} from "@playruo/embed";
+```
+
+### PostMessage Communication Types
+
+For advanced use cases where you need to handle communication with the embed iframe directly:
+
+```typescript
+import type {
+  PlayruoEmbedMessage,
+  PlayruoEmbedCommand,
+  PlayruoReadyMessage,
+  PlayruoStateUpdateMessage,
+  PlayruoPurchaseRequestMessage,
+  PlayruoDemoCompletedMessage,
+  PlayruoErrorMessage,
+  TryNowCommand,
+  BuyNowCommand,
+  GetStateCommand,
+} from "@playruo/embed";
+import { isPlayruoEmbedMessage, isPlayruoEmbedCommand } from "@playruo/embed";
+```
+
+#### Example: Custom Message Handler
+
+```typescript
+"use client";
+import { useEffect } from "react";
+import type { PlayruoEmbedMessage } from "@playruo/embed";
+import { isPlayruoEmbedMessage } from "@playruo/embed";
+
+export const MyComponent = () => {
+  useEffect(() => {
+    const handleMessage = (event: MessageEvent) => {
+      if (isPlayruoEmbedMessage(event.data)) {
+        const message = event.data as PlayruoEmbedMessage;
+        
+        switch (message.type) {
+          case 'playruo_ready':
+            console.log("Embed is ready!");
+            break;
+          case 'playruo_state_update':
+            console.log("State updated:", message.data);
+            break;
+          case 'playruo_purchase_request':
+            window.open(message.data.storeUrl, "_blank");
+            break;
+          case 'playruo_demo_completed':
+            console.log("Demo completed:", message.data.reason);
+            break;
+          case 'playruo_error':
+            console.error("Embed error:", message.data);
+            break;
+        }
+      }
+    };
+
+    window.addEventListener('message', handleMessage);
+    return () => window.removeEventListener('message', handleMessage);
+  }, []);
+
+  // ...
+};
+```
+
+#### Example: Sending Commands
+
+```typescript
+import type { PlayruoEmbedCommand } from "@playruo/embed";
 
-Named exports:
+const sendCommandToEmbed = (command: PlayruoEmbedCommand) => {
+  const iframe = document.querySelector('iframe');
+  iframe?.contentWindow?.postMessage(command, '*');
+};
+
+// Send commands
+sendCommandToEmbed({ type: 'try_now' });
+sendCommandToEmbed({ type: 'buy_now' });
+sendCommandToEmbed({ type: 'get_state' });
+```
 
-- `PlayruoEmbed`
-- `buildEmbedUrl`
-- `PlayruoEmbedState`
-- `PlayruoEmbedMessage<T>`
+### Exported Types
+
+**Component:**
+- `PlayruoEmbed` - Main React component
+- `PlayruoEmbedProps` - Component props
+- `PlayruoEmbedActions` - Actions API
+- `PlayruoEmbedRenderState` - Render state API
+- `PlayruoEmbedState` - Embed state
+- `DemoCompletedPayload` - Demo completion data
+
+**Messages (Embed → Host):**
+- `PlayruoEmbedMessage` - Union of all message types
+- `PlayruoReadyMessage`
+- `PlayruoStateUpdateMessage`
+- `PlayruoPurchaseRequestMessage`
+- `PlayruoDemoCompletedMessage`
+- `PlayruoErrorMessage`
+
+**Commands (Host → Embed):**
+- `PlayruoEmbedCommand` - Union of all command types
+- `TryNowCommand`
+- `BuyNowCommand`
+- `GetStateCommand`
+
+**Utilities:**
+- `buildEmbedUrl` - URL builder function
+- `isPlayruoEmbedMessage` - Type guard for messages
+- `isPlayruoEmbedCommand` - Type guard for commands

package/dist/index.cjs

@@ -21,7 +21,9 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   PlayruoEmbed: () => PlayruoEmbed,
-  buildEmbedUrl: () => buildEmbedUrl
+  buildEmbedUrl: () => buildEmbedUrl,
+  isPlayruoEmbedCommand: () => isPlayruoEmbedCommand,
+  isPlayruoEmbedMessage: () => isPlayruoEmbedMessage
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -66,18 +68,18 @@ var PlayruoEmbed = ({
   (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") {
+      if (!msg || typeof msg.type !== "string" || !msg.type.startsWith("playruo_")) return;
+      if (msg.type === "playruo_ready") {
         setIsReady(true);
         onReady?.();
-      } else if (msg.type === "playruo:state" || msg.type === "playruo_state_update") {
+      } else if (msg.type === "playruo_state_update") {
         setState(msg.data);
         onStateChange?.(msg.data);
-      } else if (msg.type === "playruo:demoCompleted" || msg.type === "playruo_demo_completed") {
+      } else if (msg.type === "playruo_demo_completed") {
         onDemoCompleted?.(msg.data);
-      } else if (msg.type === "playruo:purchaseRequest" || msg.type === "playruo_purchase_request") {
+      } else if (msg.type === "playruo_purchase_request") {
         onPurchaseRequest?.(msg.data);
-      } else if (msg.type === "playruo:error" || msg.type === "playruo_error") {
+      } else if (msg.type === "playruo_error") {
         const message = msg.data?.message ?? "Unknown error";
         setErrorMessage(message);
         onError?.(message);
@@ -130,8 +132,24 @@ var PlayruoEmbed = ({
     )
   ] });
 };
+
+// src/post-message-types.ts
+var isPlayruoEmbedMessage = (data) => {
+  if (!data || typeof data !== "object") return false;
+  const msg = data;
+  if (typeof msg.type !== "string") return false;
+  return msg.type === "playruo_ready" || msg.type === "playruo_state_update" || msg.type === "playruo_purchase_request" || msg.type === "playruo_demo_completed" || msg.type === "playruo_error";
+};
+var isPlayruoEmbedCommand = (data) => {
+  if (!data || typeof data !== "object") return false;
+  const cmd = data;
+  if (typeof cmd.type !== "string") return false;
+  return cmd.type === "try_now" || cmd.type === "buy_now" || cmd.type === "get_state";
+};
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   PlayruoEmbed,
-  buildEmbedUrl
+  buildEmbedUrl,
+  isPlayruoEmbedCommand,
+  isPlayruoEmbedMessage
 });

package/dist/index.d.cts

@@ -11,10 +11,6 @@ interface PlayruoEmbedState {
         status?: string;
     };
 }
-interface PlayruoEmbedMessage<T = unknown> {
-    type: `playruo:${string}`;
-    data?: T;
-}
 interface DemoCompletedPayload {
     reason?: string;
     storeUrl?: string;
@@ -56,6 +52,49 @@ interface PlayruoEmbedProps {
 }
 declare const PlayruoEmbed: FC<PlayruoEmbedProps>;
 
+interface PlayruoReadyMessage {
+    type: "playruo_ready";
+}
+interface PlayruoStateUpdateMessage {
+    type: "playruo_state_update";
+    data: PlayruoEmbedState;
+}
+interface PlayruoPurchaseRequestMessage {
+    type: "playruo_purchase_request";
+    data: {
+        storeUrl: string;
+    };
+}
+interface PlayruoDemoCompletedMessage {
+    type: "playruo_demo_completed";
+    data: DemoCompletedPayload;
+}
+interface PlayruoErrorMessage {
+    type: "playruo_error";
+    data: {
+        message: string;
+    } | string;
+}
+type PlayruoEmbedMessage = PlayruoReadyMessage | PlayruoStateUpdateMessage | PlayruoPurchaseRequestMessage | PlayruoDemoCompletedMessage | PlayruoErrorMessage;
+interface TryNowCommand {
+    type: "try_now";
+}
+interface BuyNowCommand {
+    type: "buy_now";
+}
+interface GetStateCommand {
+    type: "get_state";
+}
+type PlayruoEmbedCommand = TryNowCommand | BuyNowCommand | GetStateCommand;
+/**
+ * Type guard to check if a message event is a Playruo embed message
+ */
+declare const isPlayruoEmbedMessage: (data: unknown) => data is PlayruoEmbedMessage;
+/**
+ * Type guard to check if a command is a valid Playruo embed command
+ */
+declare const isPlayruoEmbedCommand: (data: unknown) => data is PlayruoEmbedCommand;
+
 interface BuildUrlParams {
     baseUrl: string;
     operation?: string;
@@ -63,4 +102,4 @@ interface BuildUrlParams {
 }
 declare const buildEmbedUrl: ({ baseUrl, operation, storeUrl }: BuildUrlParams) => string;
 
-export { type DemoCompletedPayload, PlayruoEmbed, type PlayruoEmbedActions, type PlayruoEmbedMessage, type PlayruoEmbedProps, type PlayruoEmbedRenderState, type PlayruoEmbedState, buildEmbedUrl };
+export { type BuyNowCommand, type DemoCompletedPayload, type GetStateCommand, type PlayruoDemoCompletedMessage, PlayruoEmbed, type PlayruoEmbedActions, type PlayruoEmbedCommand, type PlayruoEmbedMessage, type PlayruoEmbedProps, type PlayruoEmbedRenderState, type PlayruoEmbedState, type PlayruoErrorMessage, type PlayruoPurchaseRequestMessage, type PlayruoReadyMessage, type PlayruoStateUpdateMessage, type TryNowCommand, buildEmbedUrl, isPlayruoEmbedCommand, isPlayruoEmbedMessage };

package/dist/index.d.ts

@@ -11,10 +11,6 @@ interface PlayruoEmbedState {
         status?: string;
     };
 }
-interface PlayruoEmbedMessage<T = unknown> {
-    type: `playruo:${string}`;
-    data?: T;
-}
 interface DemoCompletedPayload {
     reason?: string;
     storeUrl?: string;
@@ -56,6 +52,49 @@ interface PlayruoEmbedProps {
 }
 declare const PlayruoEmbed: FC<PlayruoEmbedProps>;
 
+interface PlayruoReadyMessage {
+    type: "playruo_ready";
+}
+interface PlayruoStateUpdateMessage {
+    type: "playruo_state_update";
+    data: PlayruoEmbedState;
+}
+interface PlayruoPurchaseRequestMessage {
+    type: "playruo_purchase_request";
+    data: {
+        storeUrl: string;
+    };
+}
+interface PlayruoDemoCompletedMessage {
+    type: "playruo_demo_completed";
+    data: DemoCompletedPayload;
+}
+interface PlayruoErrorMessage {
+    type: "playruo_error";
+    data: {
+        message: string;
+    } | string;
+}
+type PlayruoEmbedMessage = PlayruoReadyMessage | PlayruoStateUpdateMessage | PlayruoPurchaseRequestMessage | PlayruoDemoCompletedMessage | PlayruoErrorMessage;
+interface TryNowCommand {
+    type: "try_now";
+}
+interface BuyNowCommand {
+    type: "buy_now";
+}
+interface GetStateCommand {
+    type: "get_state";
+}
+type PlayruoEmbedCommand = TryNowCommand | BuyNowCommand | GetStateCommand;
+/**
+ * Type guard to check if a message event is a Playruo embed message
+ */
+declare const isPlayruoEmbedMessage: (data: unknown) => data is PlayruoEmbedMessage;
+/**
+ * Type guard to check if a command is a valid Playruo embed command
+ */
+declare const isPlayruoEmbedCommand: (data: unknown) => data is PlayruoEmbedCommand;
+
 interface BuildUrlParams {
     baseUrl: string;
     operation?: string;
@@ -63,4 +102,4 @@ interface BuildUrlParams {
 }
 declare const buildEmbedUrl: ({ baseUrl, operation, storeUrl }: BuildUrlParams) => string;
 
-export { type DemoCompletedPayload, PlayruoEmbed, type PlayruoEmbedActions, type PlayruoEmbedMessage, type PlayruoEmbedProps, type PlayruoEmbedRenderState, type PlayruoEmbedState, buildEmbedUrl };
+export { type BuyNowCommand, type DemoCompletedPayload, type GetStateCommand, type PlayruoDemoCompletedMessage, PlayruoEmbed, type PlayruoEmbedActions, type PlayruoEmbedCommand, type PlayruoEmbedMessage, type PlayruoEmbedProps, type PlayruoEmbedRenderState, type PlayruoEmbedState, type PlayruoErrorMessage, type PlayruoPurchaseRequestMessage, type PlayruoReadyMessage, type PlayruoStateUpdateMessage, type TryNowCommand, buildEmbedUrl, isPlayruoEmbedCommand, isPlayruoEmbedMessage };

package/dist/index.js

@@ -39,18 +39,18 @@ var PlayruoEmbed = ({
   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") {
+      if (!msg || typeof msg.type !== "string" || !msg.type.startsWith("playruo_")) return;
+      if (msg.type === "playruo_ready") {
         setIsReady(true);
         onReady?.();
-      } else if (msg.type === "playruo:state" || msg.type === "playruo_state_update") {
+      } else if (msg.type === "playruo_state_update") {
         setState(msg.data);
         onStateChange?.(msg.data);
-      } else if (msg.type === "playruo:demoCompleted" || msg.type === "playruo_demo_completed") {
+      } else if (msg.type === "playruo_demo_completed") {
         onDemoCompleted?.(msg.data);
-      } else if (msg.type === "playruo:purchaseRequest" || msg.type === "playruo_purchase_request") {
+      } else if (msg.type === "playruo_purchase_request") {
         onPurchaseRequest?.(msg.data);
-      } else if (msg.type === "playruo:error" || msg.type === "playruo_error") {
+      } else if (msg.type === "playruo_error") {
         const message = msg.data?.message ?? "Unknown error";
         setErrorMessage(message);
         onError?.(message);
@@ -103,7 +103,23 @@ var PlayruoEmbed = ({
     )
   ] });
 };
+
+// src/post-message-types.ts
+var isPlayruoEmbedMessage = (data) => {
+  if (!data || typeof data !== "object") return false;
+  const msg = data;
+  if (typeof msg.type !== "string") return false;
+  return msg.type === "playruo_ready" || msg.type === "playruo_state_update" || msg.type === "playruo_purchase_request" || msg.type === "playruo_demo_completed" || msg.type === "playruo_error";
+};
+var isPlayruoEmbedCommand = (data) => {
+  if (!data || typeof data !== "object") return false;
+  const cmd = data;
+  if (typeof cmd.type !== "string") return false;
+  return cmd.type === "try_now" || cmd.type === "buy_now" || cmd.type === "get_state";
+};
 export {
   PlayruoEmbed,
-  buildEmbedUrl
+  buildEmbedUrl,
+  isPlayruoEmbedCommand,
+  isPlayruoEmbedMessage
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@playruo/embed",
-  "version": "1.1.2",
+  "version": "1.1.3",
   "description": "React SDK to embed Playruo with postMessage API.",
   "license": "MIT",
   "type": "module",