@playruo/embed 1.3.3 → 1.4.0

package/dist/index.d.cts

@@ -24,6 +24,106 @@ type PlayruoEventPayload = Record<string, unknown> & {
     name?: string;
 };
 
+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;
+}
+interface PlayruoSessionOverMessage {
+    type: "playruo_session_over";
+    data: PlayruoEmbedState;
+}
+interface PlayruoStreamStartMessage {
+    type: "playruo_stream_start";
+}
+interface PlayruoStreamStopMessage {
+    type: "playruo_stream_stop";
+}
+interface PlayruoRequestExitFullscreenMessage {
+    type: "REQUEST_EXIT_FULLSCREEN";
+}
+interface PlayruoEventMessage {
+    type: "playruo_event";
+    data: PlayruoEventPayload;
+}
+/**
+ * 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" | "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
+ * Messages FROM Embed → Host via postMessage
+ */
+declare const isPlayruoEmbedMessage: (data: unknown) => data is PlayruoEmbedMessage;
+/**
+ * Type guard to check if a message is a Playruo internal message
+ * Format: { type: 'playruo', action: '...', fromEmbed: true }
+ * These are messages sent TO the iframe (game), not to the parent
+ */
+declare const isPlayruoInternalMessage: (data: unknown) => data is PlayruoInternalMessage;
+
 interface PlayruoEmbedActions {
     /** Start the demo session */
     tryNow: () => void;
@@ -33,17 +133,52 @@ interface PlayruoEmbedActions {
     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;
@@ -55,6 +190,13 @@ interface PlayruoEmbedProps {
         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.
@@ -74,7 +216,7 @@ interface PlayruoEmbedProps {
     /**
      * Ref to access the iframe element for fullscreen requests
      */
-    iframeRef?: React.RefObject<HTMLIFrameElement>;
+    iframeRef?: React.RefObject<HTMLIFrameElement | null>;
 }
 declare const PlayruoEmbed: FC<PlayruoEmbedProps>;
 
@@ -90,69 +232,14 @@ interface EmbedTesterProps {
 }
 declare const EmbedTester: (props?: EmbedTesterProps) => react_jsx_runtime.JSX.Element;
 
-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;
-}
-interface PlayruoSessionOverMessage {
-    type: "playruo_session_over";
-    data: PlayruoEmbedState;
-}
-interface PlayruoStreamStartMessage {
-    type: "playruo_stream_start";
-}
-interface PlayruoStreamStopMessage {
-    type: "playruo_stream_stop";
-}
-interface PlayruoRequestExitFullscreenMessage {
-    type: "REQUEST_EXIT_FULLSCREEN";
-}
-interface PlayruoEventMessage {
-    type: "playruo_event";
-    data: PlayruoEventPayload;
-}
-type PlayruoEmbedMessage = PlayruoReadyMessage | PlayruoStateUpdateMessage | PlayruoPurchaseRequestMessage | PlayruoDemoCompletedMessage | PlayruoErrorMessage | PlayruoSessionOverMessage | PlayruoStreamStartMessage | PlayruoStreamStopMessage | PlayruoRequestExitFullscreenMessage | PlayruoEventMessage;
-interface PlayruoInternalMessage {
-    type: "playruo";
-    action: "tryNowClick" | "exitFullscreen" | "mute" | "unmute";
-    fromEmbed: true;
-    isReplay?: boolean;
-    isFullscreen?: boolean;
-    parentWillHandleFullscreen?: boolean;
-}
-/**
- * Type guard to check if a message event is a Playruo embed message
- * Messages FROM Embed → Host via postMessage
- */
-declare const isPlayruoEmbedMessage: (data: unknown) => data is PlayruoEmbedMessage;
-/**
- * Type guard to check if a message is a Playruo internal message
- * Format: { type: 'playruo', action: '...', fromEmbed: true }
- * These are messages sent TO the iframe (game), not to the parent
- */
-declare const isPlayruoInternalMessage: (data: unknown) => data is PlayruoInternalMessage;
-
 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;
 }
 /**
@@ -161,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,6 +24,106 @@ type PlayruoEventPayload = Record<string, unknown> & {
     name?: string;
 };
 
+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;
+}
+interface PlayruoSessionOverMessage {
+    type: "playruo_session_over";
+    data: PlayruoEmbedState;
+}
+interface PlayruoStreamStartMessage {
+    type: "playruo_stream_start";
+}
+interface PlayruoStreamStopMessage {
+    type: "playruo_stream_stop";
+}
+interface PlayruoRequestExitFullscreenMessage {
+    type: "REQUEST_EXIT_FULLSCREEN";
+}
+interface PlayruoEventMessage {
+    type: "playruo_event";
+    data: PlayruoEventPayload;
+}
+/**
+ * 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" | "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
+ * Messages FROM Embed → Host via postMessage
+ */
+declare const isPlayruoEmbedMessage: (data: unknown) => data is PlayruoEmbedMessage;
+/**
+ * Type guard to check if a message is a Playruo internal message
+ * Format: { type: 'playruo', action: '...', fromEmbed: true }
+ * These are messages sent TO the iframe (game), not to the parent
+ */
+declare const isPlayruoInternalMessage: (data: unknown) => data is PlayruoInternalMessage;
+
 interface PlayruoEmbedActions {
     /** Start the demo session */
     tryNow: () => void;
@@ -33,17 +133,52 @@ interface PlayruoEmbedActions {
     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;
@@ -55,6 +190,13 @@ interface PlayruoEmbedProps {
         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.
@@ -74,7 +216,7 @@ interface PlayruoEmbedProps {
     /**
      * Ref to access the iframe element for fullscreen requests
      */
-    iframeRef?: React.RefObject<HTMLIFrameElement>;
+    iframeRef?: React.RefObject<HTMLIFrameElement | null>;
 }
 declare const PlayruoEmbed: FC<PlayruoEmbedProps>;
 
@@ -90,69 +232,14 @@ interface EmbedTesterProps {
 }
 declare const EmbedTester: (props?: EmbedTesterProps) => react_jsx_runtime.JSX.Element;
 
-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;
-}
-interface PlayruoSessionOverMessage {
-    type: "playruo_session_over";
-    data: PlayruoEmbedState;
-}
-interface PlayruoStreamStartMessage {
-    type: "playruo_stream_start";
-}
-interface PlayruoStreamStopMessage {
-    type: "playruo_stream_stop";
-}
-interface PlayruoRequestExitFullscreenMessage {
-    type: "REQUEST_EXIT_FULLSCREEN";
-}
-interface PlayruoEventMessage {
-    type: "playruo_event";
-    data: PlayruoEventPayload;
-}
-type PlayruoEmbedMessage = PlayruoReadyMessage | PlayruoStateUpdateMessage | PlayruoPurchaseRequestMessage | PlayruoDemoCompletedMessage | PlayruoErrorMessage | PlayruoSessionOverMessage | PlayruoStreamStartMessage | PlayruoStreamStopMessage | PlayruoRequestExitFullscreenMessage | PlayruoEventMessage;
-interface PlayruoInternalMessage {
-    type: "playruo";
-    action: "tryNowClick" | "exitFullscreen" | "mute" | "unmute";
-    fromEmbed: true;
-    isReplay?: boolean;
-    isFullscreen?: boolean;
-    parentWillHandleFullscreen?: boolean;
-}
-/**
- * Type guard to check if a message event is a Playruo embed message
- * Messages FROM Embed → Host via postMessage
- */
-declare const isPlayruoEmbedMessage: (data: unknown) => data is PlayruoEmbedMessage;
-/**
- * Type guard to check if a message is a Playruo internal message
- * Format: { type: 'playruo', action: '...', fromEmbed: true }
- * These are messages sent TO the iframe (game), not to the parent
- */
-declare const isPlayruoInternalMessage: (data: unknown) => data is PlayruoInternalMessage;
-
 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;
 }
 /**
@@ -161,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 };