@playruo/embed 1.3.2 → 1.4.0

package/dist/index.d.cts

@@ -24,65 +24,6 @@ type PlayruoEventPayload = Record<string, unknown> & {
     name?: string;
 };
 
-interface PlayruoEmbedActions {
-    /** Start the demo session */
-    tryNow: () => void;
-    /** Request purchase (opens store URL) */
-    buyNow: () => void;
-    /** Whether try now is currently available */
-    canTryNow: boolean;
-    /** Whether buy now is currently available */
-    canBuyNow: boolean;
-}
-interface PlayruoEmbedRenderState {
-    status: "loading" | "available" | "unavailable" | "error";
-    message?: string;
-    actions: PlayruoEmbedActions;
-}
-interface PlayruoEmbedProps {
-    /** Game origin (scheme + host). Omit to use production (`https://playruo.live`). */
-    baseUrl?: string;
-    /** Game operation slug used to build the iframe URL. */
-    operation: string;
-    storeUrl?: string;
-    showIframe?: boolean;
-    className?: string;
-    onReady?: () => void;
-    onStateChange?: (state: PlayruoEmbedState) => void;
-    onDemoCompleted?: (data: DemoCompletedPayload) => void;
-    onEvent?: (data: PlayruoEventPayload) => void;
-    onPurchaseRequest?: (data: {
-        storeUrl: string;
-    }) => void;
-    onError?: (error: string) => void;
-    /**
-     * Forward playruo_event messages to the parent window when the package host
-     * itself is embedded in another iframe. Direct host pages already receive the
-     * original iframe postMessage.
-     */
-    forwardEventsToParent?: boolean;
-    /**
-     * Single render entry point representing the current status.
-     * Provides status, message, and available actions based on current state.
-     */
-    renderState?: (render: PlayruoEmbedRenderState) => ReactNode;
-    /**
-     * Ref to access the iframe element for fullscreen requests
-     */
-    iframeRef?: React.RefObject<HTMLIFrameElement>;
-}
-declare const PlayruoEmbed: FC<PlayruoEmbedProps>;
-
-interface EmbedTesterProps {
-    /** Override game origin (e.g. http://localhost:3000). Omit for production. */
-    baseUrl?: string;
-    enableConsoleLog?: boolean;
-    operation?: string;
-    storeUrl?: string;
-    className?: string;
-}
-declare const EmbedTester: (props?: EmbedTesterProps) => react_jsx_runtime.JSX.Element;
-
 interface PlayruoReadyMessage {
     type: "playruo_ready";
 }
@@ -123,14 +64,53 @@ interface PlayruoEventMessage {
     type: "playruo_event";
     data: PlayruoEventPayload;
 }
-type PlayruoEmbedMessage = PlayruoReadyMessage | PlayruoStateUpdateMessage | PlayruoPurchaseRequestMessage | PlayruoDemoCompletedMessage | PlayruoErrorMessage | PlayruoSessionOverMessage | PlayruoStreamStartMessage | PlayruoStreamStopMessage | PlayruoRequestExitFullscreenMessage | PlayruoEventMessage;
+/**
+ * Why a password submission was refused. `already_validating` answers a submit
+ * sent while another one is still being checked, so the host may simply send it
+ * again; `too_many_attempts` closes the operation for this visitor and reopens
+ * on its own after a delay.
+ */
+type PlayruoPasswordError = "invalid_password" | "already_validating" | "too_many_attempts";
+/**
+ * A refusal code as a host reads it: one of the codes above, or any other one
+ * the operation may answer with. `string & {}` rather than `string`, which
+ * would absorb the union and drop the known codes from autocompletion.
+ */
+type PlayruoPasswordErrorCode = PlayruoPasswordError | (string & {});
+/**
+ * A password protected operation announces itself once its configuration is
+ * loaded. The iframe stays invisible until a session starts, so it renders no
+ * form of its own: the host collects the password and sends it back with the
+ * submitPassword action.
+ */
+interface PlayruoPasswordRequiredMessage {
+    type: "playruo_password_required";
+}
+/**
+ * Answers a requestPassword sent to an operation that is not protected. Without
+ * it a host cannot tell "no password needed" from "the announce has not come
+ * yet", and waits forever on a gate that will never open.
+ */
+interface PlayruoPasswordNotRequiredMessage {
+    type: "playruo_password_not_required";
+}
+interface PlayruoPasswordResultMessage {
+    type: "playruo_password_result";
+    data: {
+        success: boolean;
+        error?: PlayruoPasswordErrorCode;
+    };
+}
+type PlayruoEmbedMessage = PlayruoReadyMessage | PlayruoStateUpdateMessage | PlayruoPurchaseRequestMessage | PlayruoDemoCompletedMessage | PlayruoErrorMessage | PlayruoSessionOverMessage | PlayruoStreamStartMessage | PlayruoStreamStopMessage | PlayruoRequestExitFullscreenMessage | PlayruoEventMessage | PlayruoPasswordRequiredMessage | PlayruoPasswordNotRequiredMessage | PlayruoPasswordResultMessage;
 interface PlayruoInternalMessage {
     type: "playruo";
-    action: "tryNowClick" | "exitFullscreen" | "mute" | "unmute";
+    action: "tryNowClick" | "exitFullscreen" | "mute" | "unmute" | "submitPassword" | "requestPassword";
     fromEmbed: true;
     isReplay?: boolean;
     isFullscreen?: boolean;
     parentWillHandleFullscreen?: boolean;
+    /** Only read by the submitPassword action. */
+    password?: string;
 }
 /**
  * Type guard to check if a message event is a Playruo embed message
@@ -144,8 +124,122 @@ declare const isPlayruoEmbedMessage: (data: unknown) => data is PlayruoEmbedMess
  */
 declare const isPlayruoInternalMessage: (data: unknown) => data is PlayruoInternalMessage;
 
+interface PlayruoEmbedActions {
+    /** Start the demo session */
+    tryNow: () => void;
+    /** Request purchase (opens store URL) */
+    buyNow: () => void;
+    /** Whether try now is currently available */
+    canTryNow: boolean;
+    /** Whether buy now is currently available */
+    canBuyNow: boolean;
+    /** Send the password collected by the host to a protected operation. */
+    submitPassword: (password: string) => void;
+    /**
+     * Ask the operation to announce again whether it needs a password. The
+     * announcement is emitted once, so a host that mounts late can miss it.
+     */
+    requestPassword: () => void;
+}
+interface PlayruoEmbedPasswordState {
+    /**
+     * The operation asked for a password. Stays true once it was given, so read
+     * `unlocked` for the gate itself.
+     */
+    required: boolean;
+    /**
+     * The operation said whether it is protected. Until then `required: false`
+     * only means nothing was announced yet, so a host that called
+     * `requestPassword` cannot tell an unprotected operation from a silent one.
+     */
+    checked: boolean;
+    /** A submitted password was accepted. */
+    unlocked: boolean;
+    /** Code of the last refusal, from PlayruoPasswordError when known. */
+    error?: PlayruoPasswordErrorCode;
+}
+interface PlayruoEmbedRenderState {
+    status: "loading" | "available" | "unavailable" | "error";
+    message?: string;
+    actions: PlayruoEmbedActions;
+    /**
+     * A protected operation never announces ready while it is locked, so a host
+     * that ignores this stays on `loading` for as long as the visitor has not
+     * been asked for the password.
+     */
+    password: PlayruoEmbedPasswordState;
+}
+interface PlayruoEmbedProps {
+    /** Game origin (scheme + host). Omit to use production (`https://playruo.live`). */
+    baseUrl?: string;
+    /** Game operation slug used to build the iframe URL. */
+    operation: string;
+    /**
+     * Which operation of the campaign to open, when it holds more than one. Sent
+     * as `?op=`. Without it the campaign picks its own.
+     */
+    operationKey?: string;
+    storeUrl?: string;
+    showIframe?: boolean;
+    className?: string;
+    onReady?: () => void;
+    onStateChange?: (state: PlayruoEmbedState) => void;
+    onDemoCompleted?: (data: DemoCompletedPayload) => void;
+    onEvent?: (data: PlayruoEventPayload) => void;
+    onPurchaseRequest?: (data: {
+        storeUrl: string;
+    }) => void;
+    onError?: (error: string) => void;
+    /** The operation is password protected and waits for one. */
+    onPasswordRequired?: () => void;
+    /** Answer to a submitted password. */
+    onPasswordResult?: (result: {
+        success: boolean;
+        error?: PlayruoPasswordErrorCode;
+    }) => void;
+    /**
+     * Skip the parent fullscreen request and start the experience inside the
+     * current iframe bounds. Defaults to false to preserve the current behavior.
+     */
+    enableWindowedLaunch?: boolean;
+    /**
+     * Forward playruo_event messages to the parent window when the package host
+     * itself is embedded in another iframe. Direct host pages already receive the
+     * original iframe postMessage.
+     */
+    forwardEventsToParent?: boolean;
+    /**
+     * Single render entry point representing the current status.
+     * Provides status, message, and available actions based on current state.
+     */
+    renderState?: (render: PlayruoEmbedRenderState) => ReactNode;
+    /**
+     * Ref to access the iframe element for fullscreen requests
+     */
+    iframeRef?: React.RefObject<HTMLIFrameElement | null>;
+}
+declare const PlayruoEmbed: FC<PlayruoEmbedProps>;
+
+interface EmbedTesterProps {
+    /** Override game origin (e.g. http://localhost:3000). Omit for production. */
+    baseUrl?: string;
+    enableConsoleLog?: boolean;
+    operation?: string;
+    storeUrl?: string;
+    /** Start the experience inside the iframe without requesting parent fullscreen. */
+    enableWindowedLaunch?: boolean;
+    className?: string;
+}
+declare const EmbedTester: (props?: EmbedTesterProps) => react_jsx_runtime.JSX.Element;
+
 interface BuildUrlParams {
     operation: string;
+    /**
+     * Which operation of the campaign to open, when it holds more than one. Sent
+     * as `?op=`. Without it the campaign picks its own, which is what a single
+     * operation campaign wants.
+     */
+    operationKey?: string;
     storeUrl?: string;
 }
 /**
@@ -154,6 +248,6 @@ interface BuildUrlParams {
  * buildEmbedUrl({ operation: "my-game" })
  * // => "https://playruo.live/my-game?iframe=true"
  */
-declare const buildEmbedUrl: ({ operation, storeUrl }: BuildUrlParams) => string;
+declare const buildEmbedUrl: ({ operation, operationKey, storeUrl, }: BuildUrlParams) => string;
 
-export { type DemoCompletedPayload, EmbedTester, type EmbedTesterProps, type PlayruoDemoCompletedMessage, PlayruoEmbed, type PlayruoEmbedActions, type PlayruoEmbedMessage, type PlayruoEmbedProps, type PlayruoEmbedRenderState, type PlayruoEmbedState, type PlayruoErrorMessage, type PlayruoEventMessage, type PlayruoEventPayload, type PlayruoInternalMessage, type PlayruoPurchaseRequestMessage, type PlayruoReadyMessage, type PlayruoRequestExitFullscreenMessage, type PlayruoSessionOverMessage, type PlayruoStateUpdateMessage, type PlayruoStreamStartMessage, type PlayruoStreamStopMessage, buildEmbedUrl, isPlayruoEmbedMessage, isPlayruoInternalMessage };
+export { type DemoCompletedPayload, EmbedTester, type EmbedTesterProps, type PlayruoDemoCompletedMessage, PlayruoEmbed, type PlayruoEmbedActions, type PlayruoEmbedMessage, type PlayruoEmbedPasswordState, type PlayruoEmbedProps, type PlayruoEmbedRenderState, type PlayruoEmbedState, type PlayruoErrorMessage, type PlayruoEventMessage, type PlayruoEventPayload, type PlayruoInternalMessage, type PlayruoPasswordError, type PlayruoPasswordErrorCode, type PlayruoPasswordNotRequiredMessage, type PlayruoPasswordRequiredMessage, type PlayruoPasswordResultMessage, type PlayruoPurchaseRequestMessage, type PlayruoReadyMessage, type PlayruoRequestExitFullscreenMessage, type PlayruoSessionOverMessage, type PlayruoStateUpdateMessage, type PlayruoStreamStartMessage, type PlayruoStreamStopMessage, buildEmbedUrl, isPlayruoEmbedMessage, isPlayruoInternalMessage };

package/dist/index.d.ts

@@ -24,65 +24,6 @@ type PlayruoEventPayload = Record<string, unknown> & {
     name?: string;
 };
 
-interface PlayruoEmbedActions {
-    /** Start the demo session */
-    tryNow: () => void;
-    /** Request purchase (opens store URL) */
-    buyNow: () => void;
-    /** Whether try now is currently available */
-    canTryNow: boolean;
-    /** Whether buy now is currently available */
-    canBuyNow: boolean;
-}
-interface PlayruoEmbedRenderState {
-    status: "loading" | "available" | "unavailable" | "error";
-    message?: string;
-    actions: PlayruoEmbedActions;
-}
-interface PlayruoEmbedProps {
-    /** Game origin (scheme + host). Omit to use production (`https://playruo.live`). */
-    baseUrl?: string;
-    /** Game operation slug used to build the iframe URL. */
-    operation: string;
-    storeUrl?: string;
-    showIframe?: boolean;
-    className?: string;
-    onReady?: () => void;
-    onStateChange?: (state: PlayruoEmbedState) => void;
-    onDemoCompleted?: (data: DemoCompletedPayload) => void;
-    onEvent?: (data: PlayruoEventPayload) => void;
-    onPurchaseRequest?: (data: {
-        storeUrl: string;
-    }) => void;
-    onError?: (error: string) => void;
-    /**
-     * Forward playruo_event messages to the parent window when the package host
-     * itself is embedded in another iframe. Direct host pages already receive the
-     * original iframe postMessage.
-     */
-    forwardEventsToParent?: boolean;
-    /**
-     * Single render entry point representing the current status.
-     * Provides status, message, and available actions based on current state.
-     */
-    renderState?: (render: PlayruoEmbedRenderState) => ReactNode;
-    /**
-     * Ref to access the iframe element for fullscreen requests
-     */
-    iframeRef?: React.RefObject<HTMLIFrameElement>;
-}
-declare const PlayruoEmbed: FC<PlayruoEmbedProps>;
-
-interface EmbedTesterProps {
-    /** Override game origin (e.g. http://localhost:3000). Omit for production. */
-    baseUrl?: string;
-    enableConsoleLog?: boolean;
-    operation?: string;
-    storeUrl?: string;
-    className?: string;
-}
-declare const EmbedTester: (props?: EmbedTesterProps) => react_jsx_runtime.JSX.Element;
-
 interface PlayruoReadyMessage {
     type: "playruo_ready";
 }
@@ -123,14 +64,53 @@ interface PlayruoEventMessage {
     type: "playruo_event";
     data: PlayruoEventPayload;
 }
-type PlayruoEmbedMessage = PlayruoReadyMessage | PlayruoStateUpdateMessage | PlayruoPurchaseRequestMessage | PlayruoDemoCompletedMessage | PlayruoErrorMessage | PlayruoSessionOverMessage | PlayruoStreamStartMessage | PlayruoStreamStopMessage | PlayruoRequestExitFullscreenMessage | PlayruoEventMessage;
+/**
+ * Why a password submission was refused. `already_validating` answers a submit
+ * sent while another one is still being checked, so the host may simply send it
+ * again; `too_many_attempts` closes the operation for this visitor and reopens
+ * on its own after a delay.
+ */
+type PlayruoPasswordError = "invalid_password" | "already_validating" | "too_many_attempts";
+/**
+ * A refusal code as a host reads it: one of the codes above, or any other one
+ * the operation may answer with. `string & {}` rather than `string`, which
+ * would absorb the union and drop the known codes from autocompletion.
+ */
+type PlayruoPasswordErrorCode = PlayruoPasswordError | (string & {});
+/**
+ * A password protected operation announces itself once its configuration is
+ * loaded. The iframe stays invisible until a session starts, so it renders no
+ * form of its own: the host collects the password and sends it back with the
+ * submitPassword action.
+ */
+interface PlayruoPasswordRequiredMessage {
+    type: "playruo_password_required";
+}
+/**
+ * Answers a requestPassword sent to an operation that is not protected. Without
+ * it a host cannot tell "no password needed" from "the announce has not come
+ * yet", and waits forever on a gate that will never open.
+ */
+interface PlayruoPasswordNotRequiredMessage {
+    type: "playruo_password_not_required";
+}
+interface PlayruoPasswordResultMessage {
+    type: "playruo_password_result";
+    data: {
+        success: boolean;
+        error?: PlayruoPasswordErrorCode;
+    };
+}
+type PlayruoEmbedMessage = PlayruoReadyMessage | PlayruoStateUpdateMessage | PlayruoPurchaseRequestMessage | PlayruoDemoCompletedMessage | PlayruoErrorMessage | PlayruoSessionOverMessage | PlayruoStreamStartMessage | PlayruoStreamStopMessage | PlayruoRequestExitFullscreenMessage | PlayruoEventMessage | PlayruoPasswordRequiredMessage | PlayruoPasswordNotRequiredMessage | PlayruoPasswordResultMessage;
 interface PlayruoInternalMessage {
     type: "playruo";
-    action: "tryNowClick" | "exitFullscreen" | "mute" | "unmute";
+    action: "tryNowClick" | "exitFullscreen" | "mute" | "unmute" | "submitPassword" | "requestPassword";
     fromEmbed: true;
     isReplay?: boolean;
     isFullscreen?: boolean;
     parentWillHandleFullscreen?: boolean;
+    /** Only read by the submitPassword action. */
+    password?: string;
 }
 /**
  * Type guard to check if a message event is a Playruo embed message
@@ -144,8 +124,122 @@ declare const isPlayruoEmbedMessage: (data: unknown) => data is PlayruoEmbedMess
  */
 declare const isPlayruoInternalMessage: (data: unknown) => data is PlayruoInternalMessage;
 
+interface PlayruoEmbedActions {
+    /** Start the demo session */
+    tryNow: () => void;
+    /** Request purchase (opens store URL) */
+    buyNow: () => void;
+    /** Whether try now is currently available */
+    canTryNow: boolean;
+    /** Whether buy now is currently available */
+    canBuyNow: boolean;
+    /** Send the password collected by the host to a protected operation. */
+    submitPassword: (password: string) => void;
+    /**
+     * Ask the operation to announce again whether it needs a password. The
+     * announcement is emitted once, so a host that mounts late can miss it.
+     */
+    requestPassword: () => void;
+}
+interface PlayruoEmbedPasswordState {
+    /**
+     * The operation asked for a password. Stays true once it was given, so read
+     * `unlocked` for the gate itself.
+     */
+    required: boolean;
+    /**
+     * The operation said whether it is protected. Until then `required: false`
+     * only means nothing was announced yet, so a host that called
+     * `requestPassword` cannot tell an unprotected operation from a silent one.
+     */
+    checked: boolean;
+    /** A submitted password was accepted. */
+    unlocked: boolean;
+    /** Code of the last refusal, from PlayruoPasswordError when known. */
+    error?: PlayruoPasswordErrorCode;
+}
+interface PlayruoEmbedRenderState {
+    status: "loading" | "available" | "unavailable" | "error";
+    message?: string;
+    actions: PlayruoEmbedActions;
+    /**
+     * A protected operation never announces ready while it is locked, so a host
+     * that ignores this stays on `loading` for as long as the visitor has not
+     * been asked for the password.
+     */
+    password: PlayruoEmbedPasswordState;
+}
+interface PlayruoEmbedProps {
+    /** Game origin (scheme + host). Omit to use production (`https://playruo.live`). */
+    baseUrl?: string;
+    /** Game operation slug used to build the iframe URL. */
+    operation: string;
+    /**
+     * Which operation of the campaign to open, when it holds more than one. Sent
+     * as `?op=`. Without it the campaign picks its own.
+     */
+    operationKey?: string;
+    storeUrl?: string;
+    showIframe?: boolean;
+    className?: string;
+    onReady?: () => void;
+    onStateChange?: (state: PlayruoEmbedState) => void;
+    onDemoCompleted?: (data: DemoCompletedPayload) => void;
+    onEvent?: (data: PlayruoEventPayload) => void;
+    onPurchaseRequest?: (data: {
+        storeUrl: string;
+    }) => void;
+    onError?: (error: string) => void;
+    /** The operation is password protected and waits for one. */
+    onPasswordRequired?: () => void;
+    /** Answer to a submitted password. */
+    onPasswordResult?: (result: {
+        success: boolean;
+        error?: PlayruoPasswordErrorCode;
+    }) => void;
+    /**
+     * Skip the parent fullscreen request and start the experience inside the
+     * current iframe bounds. Defaults to false to preserve the current behavior.
+     */
+    enableWindowedLaunch?: boolean;
+    /**
+     * Forward playruo_event messages to the parent window when the package host
+     * itself is embedded in another iframe. Direct host pages already receive the
+     * original iframe postMessage.
+     */
+    forwardEventsToParent?: boolean;
+    /**
+     * Single render entry point representing the current status.
+     * Provides status, message, and available actions based on current state.
+     */
+    renderState?: (render: PlayruoEmbedRenderState) => ReactNode;
+    /**
+     * Ref to access the iframe element for fullscreen requests
+     */
+    iframeRef?: React.RefObject<HTMLIFrameElement | null>;
+}
+declare const PlayruoEmbed: FC<PlayruoEmbedProps>;
+
+interface EmbedTesterProps {
+    /** Override game origin (e.g. http://localhost:3000). Omit for production. */
+    baseUrl?: string;
+    enableConsoleLog?: boolean;
+    operation?: string;
+    storeUrl?: string;
+    /** Start the experience inside the iframe without requesting parent fullscreen. */
+    enableWindowedLaunch?: boolean;
+    className?: string;
+}
+declare const EmbedTester: (props?: EmbedTesterProps) => react_jsx_runtime.JSX.Element;
+
 interface BuildUrlParams {
     operation: string;
+    /**
+     * Which operation of the campaign to open, when it holds more than one. Sent
+     * as `?op=`. Without it the campaign picks its own, which is what a single
+     * operation campaign wants.
+     */
+    operationKey?: string;
     storeUrl?: string;
 }
 /**
@@ -154,6 +248,6 @@ interface BuildUrlParams {
  * buildEmbedUrl({ operation: "my-game" })
  * // => "https://playruo.live/my-game?iframe=true"
  */
-declare const buildEmbedUrl: ({ operation, storeUrl }: BuildUrlParams) => string;
+declare const buildEmbedUrl: ({ operation, operationKey, storeUrl, }: BuildUrlParams) => string;
 
-export { type DemoCompletedPayload, EmbedTester, type EmbedTesterProps, type PlayruoDemoCompletedMessage, PlayruoEmbed, type PlayruoEmbedActions, type PlayruoEmbedMessage, type PlayruoEmbedProps, type PlayruoEmbedRenderState, type PlayruoEmbedState, type PlayruoErrorMessage, type PlayruoEventMessage, type PlayruoEventPayload, type PlayruoInternalMessage, type PlayruoPurchaseRequestMessage, type PlayruoReadyMessage, type PlayruoRequestExitFullscreenMessage, type PlayruoSessionOverMessage, type PlayruoStateUpdateMessage, type PlayruoStreamStartMessage, type PlayruoStreamStopMessage, buildEmbedUrl, isPlayruoEmbedMessage, isPlayruoInternalMessage };
+export { type DemoCompletedPayload, EmbedTester, type EmbedTesterProps, type PlayruoDemoCompletedMessage, PlayruoEmbed, type PlayruoEmbedActions, type PlayruoEmbedMessage, type PlayruoEmbedPasswordState, type PlayruoEmbedProps, type PlayruoEmbedRenderState, type PlayruoEmbedState, type PlayruoErrorMessage, type PlayruoEventMessage, type PlayruoEventPayload, type PlayruoInternalMessage, type PlayruoPasswordError, type PlayruoPasswordErrorCode, type PlayruoPasswordNotRequiredMessage, type PlayruoPasswordRequiredMessage, type PlayruoPasswordResultMessage, type PlayruoPurchaseRequestMessage, type PlayruoReadyMessage, type PlayruoRequestExitFullscreenMessage, type PlayruoSessionOverMessage, type PlayruoStateUpdateMessage, type PlayruoStreamStartMessage, type PlayruoStreamStopMessage, buildEmbedUrl, isPlayruoEmbedMessage, isPlayruoInternalMessage };