@hopecloud/jetstream-player 1.1.5 → 1.3.0-rc.1

package/README.md

@@ -1 +1,76 @@
-Docs: https://jetstream-player.docs.hope.cloud/
+# @hopecloud/jetstream-player
+
+Control an embedded [Jetstream](https://jetstream-player.docs.hope.cloud/) player
+from your page — play, pause, seek, mute, read playback state, and subscribe to
+events — across the iframe boundary, with no server glue.
+
+**[Full documentation →](https://jetstream-player.docs.hope.cloud/)**
+
+## Install
+
+```bash
+npm i @hopecloud/jetstream-player
+```
+
+## Quick start
+
+```ts
+import { JetstreamPlayer } from '@hopecloud/jetstream-player';
+
+const player = new JetstreamPlayer('#player', {
+  mediaId: 'jsv:xxxxxxxxxx',
+  events: {
+    ready: () => console.log('ready'),
+    timeupdate: (time) => console.log('time', time),
+  },
+});
+
+player.play();
+const muted = await player.isMuted();
+```
+
+`mediaId` is the only required option; the library creates and mounts the iframe
+at the given selector.
+
+## What you can do
+
+- **Commands** — `play()`, `pause()`, `mute()`, `unmute()`, `seekTo(seconds)`,
+  `playNext()`, `playPrev()`.
+- **Getters** (Promise-based) — `isMuted()`, `isPaused()`,
+  `getVideoCurrentTime()`, `getDuration()`. They reject after 5s if the player
+  doesn't reply.
+- **Events** — subscribe via `options.events`: `ready`, `timeupdate`, `play`,
+  `pause`, `loadedmetadata`, `ended`, `volumechange`, `error`.
+- **Teardown** — `dispose()` removes listeners and tears down Picture-in-Picture.
+
+See the [options](https://jetstream-player.docs.hope.cloud/api/player-options)
+and [methods](https://jetstream-player.docs.hope.cloud/api/player-methods)
+reference for the full list.
+
+## Targeting a non-prod embed
+
+By default the player loads the production embed. Point it at another host
+(staging/dev) with `origin`:
+
+```ts
+new JetstreamPlayer('#player', {
+  mediaId: 'jsv:xxxxxxxxxx',
+  origin: 'https://embed-stage.jetstream.studio',
+});
+```
+
+Communication is cross-origin `postMessage`, and the SDK learns the iframe's
+real origin at runtime — so it keeps working even when the embed redirects.
+
+## Development
+
+```bash
+pnpm install
+pnpm build       # rolldown + .d.ts
+pnpm test        # vitest
+pnpm lint
+pnpm typecheck
+pnpm docs:dev    # vitepress docs
+```
+
+Architecture decisions are recorded in [`adr/`](./adr).

package/dist/embed-frame.d.ts

@@ -0,0 +1,7 @@
+import type { EmbedFrameOptions } from './player.type';
+export declare const buildEmbedSrc: (options: EmbedFrameOptions) => string;
+export interface MountedFrame {
+    iframe: HTMLIFrameElement;
+    src: string;
+}
+export declare const mountEmbedFrame: (selector: string, options: EmbedFrameOptions) => MountedFrame;

package/dist/index.d.ts

@@ -1,3 +1,2 @@
 export { JetstreamPlayer } from './player';
 export * from './player.type';
-export * from './utils';

package/dist/index.js

@@ -1,68 +1,43 @@
-//#region src/iframe-builder.ts
-var IFrameBuilder = class {
-	options;
-	iframe = null;
-	constructor(options) {
-		this.options = options;
-		this.iframe = this.generateIframe();
-	}
-	generateIframe() {
-		const iframe = document.createElement("iframe");
-		iframe.allow = "accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture";
-		iframe.allowFullscreen = true;
-		iframe.frameBorder = "0";
-		iframe.title = "Jetstream player";
-		iframe.src = this.options.src;
-		iframe.width = this.options.width || "480px";
-		iframe.height = this.options.height || "270px";
-		iframe.classList.add("jet-stream-iframe-player");
-		return iframe;
-	}
-	insertIframe(iframe) {
-		const parent = document.querySelector(this.options.selector);
-		if (parent) parent.appendChild(iframe);
-		else console.error(`Element matching selector "${this.options.selector}" not found.`);
+//#region src/embed-frame.ts
+const DEFAULT_ORIGIN = "https://jstre.am";
+const regionOrigin = (origin, region) => {
+	const url = new URL(origin);
+	if (region === "eu") {
+		const parts = url.hostname.split(".");
+		parts.splice(parts.length > 2 ? 1 : 0, 0, "eu");
+		url.hostname = parts.join(".");
 	}
+	return url.origin;
 };
-
-//#endregion
-//#region src/iframe-builder-src.ts
-var IFrameBuilderSrc = class {
-	options;
-	origin = "https://jstre.am";
-	constructor(options) {
-		if (options.mediaId === "") throw new Error("mediaId not provided!");
-		if (!options.mediaId.startsWith("jsv:")) throw new Error("mediaId must start with \"jsv:\"");
-		if (typeof options.playerId !== "undefined") {
-			if (options.playerId === "") throw new Error("playerId not provided!");
-			if (!options.playerId.startsWith("jsp:")) throw new Error("playerId must start with \"jsp:\"");
-		}
-		this.options = options;
-	}
-	getRegionBasedOrigin() {
-		const url = new URL(this.origin);
-		const urlParts = url.hostname.split(".");
-		if (this.options.region && this.options.region === "eu") if (urlParts.length > 2) urlParts.splice(1, 0, "eu");
-		else urlParts.splice(0, 0, "eu");
-		url.hostname = urlParts.join(".");
-		return url.origin;
-	}
-	appendPath(path, builtUrl) {
-		const pathString = String(path).trim();
-		if (pathString.indexOf("/") === 0) builtUrl += pathString;
-		else builtUrl += `/${pathString}`;
-		return builtUrl;
-	}
-	buildSrc() {
-		const url = new URL(`${this.getRegionBasedOrigin()}/embed/${this.options.mediaId}`);
-		if (this.options.playerId) url.href = this.appendPath(this.options.playerId, url.href);
-		if (this.options.region === "eu") url.searchParams.append("region", "eu");
-		if (this.options.audioLang) url.searchParams.append("audioLang", this.options.audioLang.toLowerCase());
-		if (this.options.subtitleLang) url.searchParams.append("subtitleLang", this.options.subtitleLang.toLowerCase());
-		return url.href;
-	}
+const buildEmbedSrc = (options) => {
+	if (options.mediaId === "") throw new Error("mediaId not provided!");
+	const origin = regionOrigin(options.origin ?? DEFAULT_ORIGIN, options.region);
+	const path = options.playerId ? `/embed/${options.mediaId}/${options.playerId}` : `/embed/${options.mediaId}`;
+	const url = new URL(`${origin}${path}`);
+	if (options.region === "eu") url.searchParams.append("region", "eu");
+	if (options.audioLang) url.searchParams.append("audioLang", options.audioLang.toLowerCase());
+	if (options.subtitleLang) url.searchParams.append("subtitleLang", options.subtitleLang.toLowerCase());
+	return url.href;
+};
+const mountEmbedFrame = (selector, options) => {
+	const src = buildEmbedSrc(options);
+	const iframe = document.createElement("iframe");
+	iframe.allow = "accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture";
+	iframe.allowFullscreen = true;
+	iframe.frameBorder = "0";
+	iframe.title = "Jetstream player";
+	iframe.src = src;
+	iframe.width = options.width || "480px";
+	iframe.height = options.height || "270px";
+	iframe.classList.add("jet-stream-iframe-player");
+	const parent = document.querySelector(selector);
+	if (parent) parent.appendChild(iframe);
+	else console.error(`Element matching selector "${selector}" not found.`);
+	return {
+		iframe,
+		src
+	};
 };
-
 //#endregion
 //#region src/iframe-pip-plugin.ts
 const PiP_STYLES = {
@@ -73,6 +48,8 @@ const PiP_STYLES = {
 	height: "180px"
 };
 var IFramePiPPlugin = class {
+	containerSelector;
+	iframe;
 	observer = null;
 	originalParentHeight = null;
 	originalIframeStyle = null;
@@ -125,142 +102,188 @@ var IFramePiPPlugin = class {
 		this.destroy();
 	}
 };
-
 //#endregion
-//#region src/utils.ts
-const normalizeEventData = (event) => {
-	return JSON.parse(event.data);
-};
-const denormalizeEventData = (data) => {
-	return JSON.stringify(data);
-};
-const isValidEventData = (rawData) => {
-	if (typeof rawData !== "string") return false;
+//#region src/protocol.ts
+const encode = (command) => JSON.stringify(command);
+const decode = (raw) => {
+	if (typeof raw !== "string") return null;
 	try {
-		JSON.parse(rawData);
-		return true;
-	} catch (error) {
-		console.log("Error parsing JSON", error);
-		return false;
+		const parsed = JSON.parse(raw);
+		if (typeof parsed === "object" && parsed !== null && typeof parsed.type === "string") return parsed;
+		return null;
+	} catch {
+		return null;
+	}
+};
+//#endregion
+//#region src/player-bridge.ts
+const REQUEST_TIMEOUT_MS = 5e3;
+var PlayerBridge = class {
+	transport;
+	targetOrigin;
+	listeners = /* @__PURE__ */ new Set();
+	detach;
+	constructor(transport, initialTargetOrigin) {
+		this.transport = transport;
+		this.targetOrigin = initialTargetOrigin;
+		this.detach = this.transport.subscribe((message, origin) => {
+			const event = decode(message);
+			if (!event) return;
+			this.targetOrigin = origin;
+			this.listeners.forEach((listener) => listener(event));
+		});
+	}
+	send(command) {
+		this.transport.send(encode(command), this.targetOrigin);
+	}
+	subscribe(listener) {
+		this.listeners.add(listener);
+		return () => {
+			this.listeners.delete(listener);
+		};
+	}
+	request(command, timeoutMs = REQUEST_TIMEOUT_MS) {
+		return new Promise((resolve, reject) => {
+			let off = () => void 0;
+			const timer = setTimeout(() => {
+				off();
+				reject(/* @__PURE__ */ new Error(`Timed out waiting for "${command.name}" response`));
+			}, timeoutMs);
+			off = this.subscribe((event) => {
+				if (event.type === command.name) {
+					clearTimeout(timer);
+					off();
+					resolve(event.value);
+				}
+			});
+			this.send(command);
+		});
+	}
+	dispose() {
+		this.detach();
+		this.listeners.clear();
 	}
 };
-
+//#endregion
+//#region src/player-transport.ts
+const windowTransport = (iframe) => ({
+	send: (message, targetOrigin) => {
+		iframe.contentWindow?.postMessage(message, targetOrigin);
+	},
+	subscribe: (handler) => {
+		const listener = (event) => {
+			if (event.source !== iframe.contentWindow) return;
+			handler(event.data, event.origin);
+		};
+		window.addEventListener("message", listener);
+		return () => {
+			window.removeEventListener("message", listener);
+		};
+	}
+});
 //#endregion
 //#region src/player.ts
 var JetstreamPlayer = class {
-	iframe = null;
 	options;
-	registeredEvents = {};
+	listeners = /* @__PURE__ */ new Map();
 	iFramePiP = null;
-	targetOrigin = "*";
-	boundSubscribeEventHandler;
+	bridge = null;
 	constructor(el, options) {
 		this.options = options;
-		const src = new IFrameBuilderSrc({
-			mediaId: options.mediaId,
-			playerId: options.playerId,
-			region: options.region
-		}).buildSrc();
+		const { iframe, src } = mountEmbedFrame(el, options);
+		let initialTargetOrigin;
 		try {
-			this.targetOrigin = new URL(src).origin;
+			initialTargetOrigin = new URL(src).origin;
 		} catch {
-			this.targetOrigin = "*";
-		}
-		const iframeBuilder = new IFrameBuilder({
-			selector: el,
-			src,
-			width: this.options.width,
-			height: this.options.height
-		});
-		this.iframe = iframeBuilder.iframe;
-		this.boundSubscribeEventHandler = this.subscribeEventHandler.bind(this);
-		if (this.iframe) {
-			iframeBuilder.insertIframe(this.iframe);
-			this.iframe.addEventListener("load", () => {
-				this.registerEvents();
-				this.subscribeToRegisteredEvents();
-			}, { once: true });
-			if (typeof this.options.sticky !== "undefined" && this.options.sticky) this.iFramePiP = new IFramePiPPlugin(el, this.iframe);
+			initialTargetOrigin = "*";
 		}
+		this.bridge = new PlayerBridge(windowTransport(iframe), initialTargetOrigin);
+		iframe.addEventListener("load", () => {
+			this.registerEvents();
+			this.bridge?.subscribe((event) => {
+				this.emit(event.type, event.value);
+			});
+		}, { once: true });
+		if (typeof this.options.sticky !== "undefined" && this.options.sticky) this.iFramePiP = new IFramePiPPlugin(el, iframe);
 	}
 	registerEvents() {
-		if (!this.options.events || this.options.events && Object.keys(this.options.events).length === 0) return;
-		Object.entries(this.options.events).forEach(([eventName, cb]) => {
-			if (!(eventName in this.registeredEvents)) this.registeredEvents[eventName] = cb;
+		if (!this.options.events) return;
+		Object.entries(this.options.events).forEach(([eventName, handler]) => {
+			if (handler) this.on(eventName, handler);
 		});
 	}
-	subscribeEventHandler(event) {
-		if (!this.iframe?.contentWindow) return;
-		if (event.source !== this.iframe.contentWindow) return;
-		if (this.targetOrigin !== "*" && event.origin !== this.targetOrigin) return;
-		if (!isValidEventData(event.data)) return;
-		const data = normalizeEventData(event);
-		const eventType = data.type;
-		const handler = this.registeredEvents[eventType];
-		if (handler) handler(data.value);
+	emit(type, value) {
+		const handlers = this.listeners.get(type);
+		if (!handlers) return;
+		[...handlers].forEach((handler) => handler(value));
 	}
-	subscribeToRegisteredEvents() {
-		window.addEventListener("message", this.boundSubscribeEventHandler);
+	on(event, handler) {
+		let handlers = this.listeners.get(event);
+		if (!handlers) {
+			handlers = /* @__PURE__ */ new Set();
+			this.listeners.set(event, handlers);
+		}
+		handlers.add(handler);
+		return () => {
+			this.off(event, handler);
+		};
 	}
-	dispatch(event) {
-		if (!this.iframe || !this.iframe.contentWindow) throw new Error("iframe is not provided or parent window not found!");
-		this.iframe.contentWindow.postMessage(denormalizeEventData(event), this.targetOrigin);
+	off(event, handler) {
+		if (!handler) {
+			this.listeners.delete(event);
+			return;
+		}
+		const handlers = this.listeners.get(event);
+		if (!handlers) return;
+		handlers.delete(handler);
+		if (handlers.size === 0) this.listeners.delete(event);
 	}
-	getterDispatch(getterEvent) {
-		return new Promise((resolve) => {
-			this.dispatch(getterEvent);
-			window.addEventListener("message", (event) => {
-				if (event.source !== this.iframe?.contentWindow) return;
-				if (this.targetOrigin !== "*" && event.origin !== this.targetOrigin) return;
-				if (!isValidEventData(event.data)) return;
-				const data = normalizeEventData(event);
-				if (data.type === getterEvent.name) resolve(data.value);
-			}, { once: true });
-		});
+	request(command) {
+		if (!this.bridge) return Promise.reject(/* @__PURE__ */ new Error("iframe is not provided or parent window not found!"));
+		return this.bridge.request(command);
 	}
 	play() {
-		this.dispatch({ name: "play" });
+		this.bridge?.send({ name: "play" });
 	}
 	pause() {
-		this.dispatch({ name: "pause" });
+		this.bridge?.send({ name: "pause" });
 	}
 	mute() {
-		this.dispatch({ name: "mute" });
+		this.bridge?.send({ name: "mute" });
 	}
 	unmute() {
-		this.dispatch({ name: "unmute" });
+		this.bridge?.send({ name: "unmute" });
 	}
 	seekTo(seconds) {
-		this.dispatch({
+		this.bridge?.send({
 			name: "seekTo",
 			params: seconds
 		});
 	}
 	playNext() {
-		this.dispatch({ name: "play-next" });
+		this.bridge?.send({ name: "play-next" });
 	}
 	playPrev() {
-		this.dispatch({ name: "play-prev" });
+		this.bridge?.send({ name: "play-prev" });
 	}
 	isMuted() {
-		return this.getterDispatch({ name: "is-muted" });
+		return this.request({ name: "is-muted" });
 	}
 	isPaused() {
-		return this.getterDispatch({ name: "is-paused" });
+		return this.request({ name: "is-paused" });
 	}
 	getVideoCurrentTime() {
-		return this.getterDispatch({ name: "get-video-current-time" });
+		return this.request({ name: "get-video-current-time" });
 	}
 	getDuration() {
-		return this.getterDispatch({ name: "get-duration" });
+		return this.request({ name: "get-duration" });
 	}
 	dispose() {
-		window.removeEventListener("message", this.boundSubscribeEventHandler);
-		this.registeredEvents = {};
+		this.bridge?.dispose();
+		this.listeners.clear();
 		this.iFramePiP?.destroy();
 	}
 };
-
 //#endregion
 //#region src/player.type.ts
 const playerListenEvents = [
@@ -273,6 +296,5 @@ const playerListenEvents = [
 	"volumechange",
 	"error"
 ];
-
 //#endregion
-export { JetstreamPlayer, denormalizeEventData, isValidEventData, normalizeEventData, playerListenEvents };
+export { JetstreamPlayer, playerListenEvents };

package/dist/player-bridge.d.ts

@@ -0,0 +1,13 @@
+import type { PlayerCommand, PlayerEvent } from './player.type';
+import type { PlayerTransport } from './player-transport';
+export declare class PlayerBridge {
+    private readonly transport;
+    private targetOrigin;
+    private readonly listeners;
+    private readonly detach;
+    constructor(transport: PlayerTransport, initialTargetOrigin: string);
+    send(command: PlayerCommand): void;
+    subscribe(listener: (event: PlayerEvent) => void): () => void;
+    request<T>(command: PlayerCommand, timeoutMs?: number): Promise<T>;
+    dispose(): void;
+}

package/dist/player-transport.d.ts

@@ -0,0 +1,5 @@
+export interface PlayerTransport {
+    send(message: string, targetOrigin: string): void;
+    subscribe(handler: (message: string, origin: string) => void): () => void;
+}
+export declare const windowTransport: (iframe: HTMLIFrameElement) => PlayerTransport;

package/dist/player.d.ts

@@ -1,17 +1,15 @@
-import type { JetstreamPlayerOptions } from './player.type';
+import type { PlayerEvents, JetstreamPlayerOptions, PlayerEventHandler } from './player.type';
 export declare class JetstreamPlayer {
-    private iframe;
     private options;
-    private registeredEvents;
+    private readonly listeners;
     private iFramePiP;
-    private targetOrigin;
-    private boundSubscribeEventHandler;
+    private bridge;
     constructor(el: string, options: JetstreamPlayerOptions);
     private registerEvents;
-    private subscribeEventHandler;
-    private subscribeToRegisteredEvents;
-    private dispatch;
-    private getterDispatch;
+    private emit;
+    on(event: PlayerEvents, handler: PlayerEventHandler): () => void;
+    off(event: PlayerEvents, handler?: PlayerEventHandler): void;
+    private request;
     play(): void;
     pause(): void;
     mute(): void;

package/dist/player.type.d.ts

@@ -5,25 +5,23 @@ export interface PlayerEvent {
     type: PlayerEvents | PlayerGetterEvents;
     value?: unknown;
 }
+export type PlayerEventHandler = (value?: unknown) => void;
 export type PlayerCommandEvent = 'play' | 'pause' | 'mute' | 'unmute' | 'seekTo' | 'play-next' | 'play-prev';
 export interface PlayerCommand {
     name: PlayerCommandEvent | PlayerGetterEvents;
     params?: unknown;
 }
-export interface IFrameBuilderOpt {
-    selector: string;
-    src: string;
-    width?: string;
-    height?: string;
-}
-export interface IFrameBuilderSrcOpt {
+export interface EmbedFrameOptions {
     mediaId: string;
     playerId?: string;
     region?: 'eu';
     audioLang?: string;
     subtitleLang?: string;
+    origin?: string;
+    width?: string;
+    height?: string;
 }
 export type JetstreamPlayerOptions = {
     sticky?: boolean;
-    events?: Partial<Record<PlayerEvents, (value?: unknown) => void>>;
-} & Omit<IFrameBuilderOpt, 'selector' | 'src'> & IFrameBuilderSrcOpt;
+    events?: Partial<Record<PlayerEvents, PlayerEventHandler>>;
+} & EmbedFrameOptions;

package/dist/protocol.d.ts

@@ -0,0 +1,3 @@
+import type { PlayerCommand, PlayerEvent } from './player.type';
+export declare const encode: (command: PlayerCommand) => string;
+export declare const decode: (raw: string) => PlayerEvent | null;

package/package.json

@@ -1,15 +1,25 @@
 {
   "name": "@hopecloud/jetstream-player",
-  "version": "1.1.5",
+  "version": "1.3.0-rc.1",
   "description": "Jetstream Embed Player SDK",
   "type": "module",
+  "sideEffects": false,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hopechannel/hopecloud.git",
+    "directory": "libs/jetstream-player"
+  },
+  "homepage": "https://jetstream-player.docs.hope.cloud/",
+  "engines": {
+    "node": "24"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
   "main": "dist/index.js",
   "files": [
     "dist"
   ],
-  "engines": {
-    "node": "24"
-  },
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -20,17 +30,14 @@
     "email": "code@deepvision.software",
     "name": "DV Software"
   },
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/hopechannel/jetstream-player"
-  },
   "devDependencies": {
-    "@deepvision/eslint-plugin": "2.0.0-rc.10",
-    "@types/node": "^24.10.9",
+    "@deepvision/eslint-plugin": "2.0.3",
+    "@types/node": "24.12.0",
+    "eslint": "10.1.0",
     "happy-dom": "^20.4.0",
-    "rolldown": "^1.0.0-beta.53",
-    "typescript": "^5.9.3",
-    "vitepress": "1.6.4",
+    "rolldown": "^1.1.4",
+    "typescript": "6.0.3",
+    "vitepress": "^1.6.4",
     "vitest": "^4.0.18"
   },
   "scripts": {
@@ -40,7 +47,7 @@
     "docs:preview": "vitepress preview docs",
     "lint": "eslint",
     "lint:fix": "eslint --fix",
-    "typecheck": "tsc --noEmit",
+    "type-check": "tsc --noEmit",
     "test": "vitest",
     "test:run": "vitest run"
   }

package/dist/iframe-builder-src.d.ts

@@ -1,9 +0,0 @@
-import { type IFrameBuilderSrcOpt } from './player.type';
-export declare class IFrameBuilderSrc {
-    private options;
-    origin: string;
-    constructor(options: IFrameBuilderSrcOpt);
-    getRegionBasedOrigin(): string;
-    appendPath(path: string, builtUrl: string): string;
-    buildSrc(): string;
-}

package/dist/iframe-builder.d.ts

@@ -1,8 +0,0 @@
-import { type IFrameBuilderOpt } from './player.type';
-export declare class IFrameBuilder {
-    options: IFrameBuilderOpt;
-    iframe: HTMLIFrameElement | null;
-    constructor(options: IFrameBuilderOpt);
-    private generateIframe;
-    insertIframe(iframe: HTMLIFrameElement): void;
-}

package/dist/utils.d.ts

@@ -1,3 +0,0 @@
-export declare const normalizeEventData: <T = unknown>(event: MessageEvent<string>) => T;
-export declare const denormalizeEventData: <T = unknown>(data: T) => string;
-export declare const isValidEventData: (rawData: string) => boolean;