@playruo/embed 1.2.0 → 1.2.2

package/README.md

@@ -1,302 +1,3 @@
 # @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
-"use client";
-import { PlayruoEmbed } from "@playruo/embed";
-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
-
-- **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, 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
-
-- **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 };
-}
-```
-
-## Actions API
-
-The `renderState` callback receives an `actions` object with:
-
-- **`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
-
-```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"` → `onReady()`
-- `"playruo_state_update"` → `onStateChange(state)`
-- `"playruo_demo_completed"` → `onDemoCompleted(data)`
-- `"playruo_purchase_request"` → `onPurchaseRequest({ storeUrl })`
-- `"playruo_error"` → `onError(message)`
-
-## URL builder (Advanced)
-
-For advanced use cases, you can build the iframe URL manually:
-
-```ts
-import { buildEmbedUrl } from "@playruo/embed";
-
-const url = buildEmbedUrl({
-  baseUrl: "https://playruo.example.com",
-  operation: "iframe", // optional, default: "iframe"
-  storeUrl: "https://store.steampowered.com/app/2751000/...", // 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 *"`.
-
-## 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";
-
-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' });
-```
-
-### 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