@rixl/media-core 0.0.0-stage → 1.0.1

package/LICENSE.md

@@ -0,0 +1 @@
+Use of this SDK is subject to our [Terms of Use](https://rixl.com/en/mediasdk-terms/).

package/README.md

@@ -1,3 +1,119 @@
-# Temporary Holding Version
+# RIXL Media SDK
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The [RIXL Media SDK](https://rixl.com/en/docs/mediasdk) enables you to build custom media experiences with RIXL's core technology through a highly optimized TypeScript library.
+
+The library provides a framework-agnostic foundation for media playback experiences: fetching, caching, player state stores, analytics, and pure helpers for progress, buffering, chapters, captions, and more. It powers the UI components in `@rixl/media-react`, `@rixl/media-vue`, `@rixl/media-svelte`, `@rixl/media-angular`, `@rixl/media-astro`, and `@rixl/media-lit`, and can be used directly from any JavaScript/TypeScript project (vanilla, custom web components, Node.js).
+
+Use of this SDK is subject to our [Terms of Use](https://rixl.com/en/mediasdk-terms/).
+
+## Installation
+
+For headless usage, install the core package. For UI components, install only your framework package (`@rixl/media-react`, `@rixl/media-vue`, `@rixl/media-svelte`, `@rixl/media-angular`, `@rixl/media-astro`, or `@rixl/media-lit`); it installs core automatically and exposes the same APIs through its `/core` subpath.
+
+```bash
+npm install @rixl/media-core
+# or
+pnpm add @rixl/media-core
+# or
+bun add @rixl/media-core
+```
+
+## Media Fetching
+
+| Function                                | Description                         |
+| --------------------------------------- | ----------------------------------- |
+| `getImage(imageId)`                     | Fetches image data by ID            |
+| `getVideo(videoId)`                     | Fetches video data by ID            |
+| `getFeedPost(feedId, postId)`           | Fetches a single post from a feed   |
+| `getFeedPosts(feedId, offset?, limit?)` | Fetches paginated posts from a feed |
+
+### Usage:
+
+```typescript
+// Fetch image data
+const imageData = await getImage("image-id");
+
+// Fetch video data
+const videoData = await getVideo("video-id");
+
+// Fetch a single post from a feed
+const post = await getFeedPost("feed-id", "post-id");
+
+// Fetch paginated posts from a feed
+const posts = await getFeedPosts("feed-id", 0, 10);
+```
+
+### TypeScript Types
+
+The library exports the following TypeScript types:
+
+| Type                | Description                                    |
+| ------------------- | ---------------------------------------------- |
+| `ImageData`         | Image metadata and URLs                        |
+| `VideoData`         | Video metadata, URLs, and playback information |
+| `FeedPost`          | Feed post content and metadata                 |
+| `FeedPostsResponse` | Paginated response for feed posts              |
+| `FileStatus`        | Status of a media file                         |
+| `FileData`          | Generic file metadata                          |
+
+## Player State
+
+Reactive [nanostores](https://github.com/nanostores/nanostores) for media playback state. All stores are framework-agnostic; consume them in React via `@nanostores/react`, in Vue via `@nanostores/vue`, etc.
+
+| Store                         | Description                                                             |
+| ----------------------------- | ----------------------------------------------------------------------- |
+| `playerStateStore`            | Per-player playback state (mute, volume, rate, tracks, fullscreen, PiP) |
+| `controlsStore`               | UI controls visibility/state                                            |
+| `settingsStore`               | User settings (caption styling, language preferences, playback speed)   |
+| `postStore`                   | Active post/content metadata                                            |
+| `analyticsStore`              | Watched-segments tracking for analytics payloads                        |
+| `feedStore`                   | Feed interaction state (transitions, initialization)                    |
+| `feedCacheStore`              | Cached feed pages                                                       |
+| `playerContainerElementStore` | Reference to the active player container element                        |
+| `playerMediaElementStore`     | Reference to the active media element                                   |
+
+## Progress Bar & Player UI Actions
+
+| Function                                        | Description                                         |
+| ----------------------------------------------- | --------------------------------------------------- |
+| `initProgressBar({video, ...})`                 | Wires drag/seek interactions to a video element     |
+| `showPlayerControls()` / `hidePlayerControls()` | Toggle controls visibility                          |
+| `togglePlayerFullscreen()`                      | Enter/exit fullscreen for the active player         |
+| `togglePlayerPictureInPicture()`                | Enter/exit picture-in-picture for the active player |
+
+## Pure Helpers
+
+Selected utilities (fully tree-shakeable):
+
+- **Progress / buffer:** `computeProgressFraction`, `computeBufferRanges`, `computeBufferedAhead`
+- **Chapters & heatmap:** `calculateChaptersWithEnd`, `calculateHeatmapSlices`, `sliceHeatmapData`, `validateChapters`
+- **Subtitles & captions:** `extractSubtitleTracks`, `processCues`, `findNextCue`, `calculateFontSize`, `constrainPercentagePosition`
+- **Volume / fullscreen / PiP:** `calculateVolumeToSet`, `shouldBeMuted`, `isEffectivelyMuted`, `isDocumentFullscreen`, `togglePictureInPicture`
+- **Persistence:** `getPersistedProgress`, `persistProgress`, `getPersistedAudioTrack`, `getPersistedSubtitleTrack`, `loadSettings`, `saveSettings`
+- **HLS / quality:** `sortLevelsByQuality`, `generateLevelName`, `getQualityLabel`, `isHlsStream`
+- **Analytics:** `postContentEvent`, `buildVideoAnalyticsPayload`, `buildContentViewEvent`, `calculateWatchDuration`
+- **Formatting:** `formatTime`, `formatNumber`, `formatNumberSm`, `clamp`, `hexToRGB`, `hexToRGBAString`
+
+## API Reference
+
+All data is fetched from `https://api.rixl.com`.
+
+### REST Endpoints
+
+| Endpoint                                                        | Description                                   |
+| --------------------------------------------------------------- | --------------------------------------------- |
+| `GET /images/{imageId}`                                         | Fetch image metadata and URLs                 |
+| `GET /videos/{videoId}`                                         | Fetch video metadata and playback information |
+| `GET /feeds/{feedId}/posts?offset=...&limit=...`                | Fetch paginated feed posts                    |
+| `GET /feeds/{feedId}/posts/{postId}`                            | Fetch a specific feed post                    |
+| `GET /feeds/{feedId}/creators/{creatorId}?offset=...&limit=...` | Fetch posts by a specific creator             |
+
+## Documentation
+
+For complete documentation, tutorials, and examples, visit our **[SDK Documentation](https://docs.rixl.com/en/sdk/getting-started)**.
+
+## Need Help?
+
+- [Developer Support](https://support.rixl.com)
+- [Developer Forum](https://forum.rixl.com)
+- [Premier Developer Support](https://rixl.com/pricing) (priority support)

package/dist/api/analytics.d.ts

@@ -0,0 +1,16 @@
+import { BuildEngagementParams, BuildErrorParams, BuildInteractionParams } from "../lib/analytics-builders.js";
+import { AnalyticsEvent } from "../types/analytics.js";
+export declare function postAnalytics(events: AnalyticsEvent[]): Promise<void>;
+export declare function postEngagement(params: BuildEngagementParams): void;
+export declare function postInteraction(params: BuildInteractionParams): void;
+export declare function postError(params: BuildErrorParams): void;
+/**
+ * Resolves once the events outstanding at call time have been sent, rather than
+ * once a flush has merely been started. Two paths used to return early: a call
+ * during an active flush reported a drain that had not happened, and a call
+ * while the only outstanding batch was already in flight (so the queue looked
+ * empty) returned before that request finished. Delegating to flushQueue makes
+ * it wait for whichever drain covers the outstanding work — starting one now,
+ * bypassing the timer, when nothing is running yet.
+ */
+export declare function flushAnalytics(): Promise<void>;

package/dist/api/analytics.js

@@ -0,0 +1,227 @@
+import { analyticsContextStore } from "../store/analytics-context-store.js";
+import { getOrCreateDeviceId } from "../store/analytics-device-store.js";
+import { getOrCreateSessionId, hasSessionStarted, markSessionStarted } from "../store/analytics-session-store.js";
+import { buildEngagementEvent, buildErrorEvent, buildInteractionEvent, buildSessionStartEvent } from "../lib/analytics-builders.js";
+import { filterUndefined } from "../lib/filter-undefined.js";
+import { toWireEvent } from "../lib/analytics-wire.js";
+import { analyticsV1EventsServiceTrackEvents } from "@rixl/sdk";
+
+// src/api/analytics.ts
+const MAX_RETRIES = 3;
+/**
+* Statuses worth sending again. 5xx and these are transient by definition;
+* every other 4xx means the endpoint understood the payload and rejected it,
+* so repeating it only wastes attempts and holds up the queue behind a batch
+* that can never drain.
+*/
+const SERVER_ERROR_MIN_STATUS = 500;
+const RETRYABLE_CLIENT_STATUSES = /* @__PURE__ */ new Set([
+	408,
+	425,
+	429
+]);
+function isRetryableStatus(status) {
+	return status >= SERVER_ERROR_MIN_STATUS || RETRYABLE_CLIENT_STATUSES.has(status);
+}
+function deliveryError(message, retryable) {
+	return Object.assign(new Error(message), { retryable });
+}
+/**
+* Anything that is not a classified delivery failure — a thrown network error,
+* an aborted request — has no response behind it and is assumed transient, so
+* events are kept rather than discarded on an unknown fault.
+*/
+function isRetryableError(error) {
+	return error instanceof Error && "retryable" in error ? error.retryable : true;
+}
+let queue = [];
+let isFlushing = false;
+let flushTimer = null;
+/**
+* The drain in progress, or null when none is running. flushAnalytics awaits
+* it so an explicit flush resolves only once the outstanding request finishes,
+* not the moment the queue looks empty because its batch is already in flight.
+*/
+let flushing = null;
+/**
+* Callers waiting on the events currently queued but not yet handed to a
+* request. One deferred covers the whole queue: a batch is taken and its
+* waiters settled together, and anything enqueued afterwards starts a new one.
+*/
+let pending = null;
+function createDeferred() {
+	let resolve = () => {};
+	return {
+		promise: new Promise((res) => {
+			resolve = res;
+		}),
+		resolve
+	};
+}
+/** Settles and clears the current deferred, if any. */
+function settlePending() {
+	const waiting = pending;
+	pending = null;
+	waiting?.resolve();
+}
+/**
+* No timer is armed while a flush is running. The running flush drains what
+* arrives during its own request, so arming one here would let it fire mid
+* request, find `isFlushing` set, and return having abandoned its waiters.
+*/
+function scheduleFlush() {
+	pending ??= createDeferred();
+	if (flushTimer === null && !isFlushing) flushTimer = setTimeout(() => {
+		flushTimer = null;
+		flushQueue();
+	}, 0);
+	return pending.promise;
+}
+/**
+* Starts a drain unless one is already running, and hands back a promise that
+* settles when the whole cycle finishes — the request in flight included, not
+* just the events still waiting in the queue. Nudge callers `void` it; only
+* flushAnalytics awaits it, so an explicit flush cannot resolve early while a
+* request it should cover is still outstanding.
+*/
+function flushQueue() {
+	if (isFlushing) return flushing ?? Promise.resolve();
+	if (queue.length === 0) return Promise.resolve();
+	const run = drainQueue().finally(() => {
+		if (flushing === run) flushing = null;
+	});
+	flushing = run;
+	return run;
+}
+async function drainQueue() {
+	isFlushing = true;
+	if (flushTimer) {
+		clearTimeout(flushTimer);
+		flushTimer = null;
+	}
+	try {
+		while (queue.length > 0) {
+			const batch = queue;
+			queue = [];
+			const waiters = pending;
+			pending = null;
+			try {
+				await performFlush(batch);
+			} catch (error) {
+				handleFailedBatch(batch, error);
+				waiters?.resolve();
+				settlePending();
+				return;
+			}
+			waiters?.resolve();
+		}
+	} finally {
+		isFlushing = false;
+	}
+}
+/**
+* Transient failures keep their events for a later flush; a rejected payload is
+* dropped, since requeueing it would block everything behind a batch the
+* endpoint will refuse again.
+*/
+function handleFailedBatch(batch, error) {
+	console.error("[Analytics] Failed to flush queue:", error);
+	if (isRetryableError(error)) queue.unshift(...batch);
+}
+async function performFlush(events) {
+	const options = {
+		context: analyticsContextStore.get(),
+		deviceId: getOrCreateDeviceId(),
+		sessionId: getOrCreateSessionId()
+	};
+	const carriesSessionStart = !hasSessionStarted();
+	await sendWithRetry(buildTrackRequest(buildPayloadEvents(events, options.context, carriesSessionStart), options));
+	if (carriesSessionStart) markSessionStarted();
+}
+function buildPayloadEvents(events, context, withSessionStart) {
+	const payloadEvents = [];
+	if (withSessionStart) payloadEvents.push(buildSessionStartEventFromContext(context));
+	payloadEvents.push(...events);
+	return payloadEvents;
+}
+function buildTrackRequest(events, options) {
+	const metadata = filterUndefined({
+		user_id: options.context.user_id,
+		country: options.context.country,
+		city: options.context.city,
+		region: options.context.region,
+		device: options.context.device,
+		os: options.context.os,
+		os_version: options.context.os_version,
+		language: options.context.language,
+		browser: options.context.browser
+	});
+	return {
+		events: events.map((event) => toWireEvent(event, options)),
+		...metadata
+	};
+}
+async function sendWithRetry(request) {
+	let lastError;
+	for (let attempt = 0; attempt < MAX_RETRIES; attempt++) try {
+		await sendEvents(request);
+		return;
+	} catch (error) {
+		lastError = error;
+		if (!isRetryableError(error)) break;
+	}
+	throw lastError;
+}
+async function sendEvents(request) {
+	const { response } = await analyticsV1EventsServiceTrackEvents({ body: request });
+	if (response && !response.ok) {
+		console.error(`[Analytics] Failed to post events: ${response.status} ${response.statusText}`);
+		throw deliveryError(`Analytics request failed with ${response.status}`, isRetryableStatus(response.status));
+	}
+}
+function buildSessionStartEventFromContext(context) {
+	return buildSessionStartEvent({
+		browser: context.browser,
+		language: context.language,
+		screenResolution: context.screen_resolution,
+		platform: context.platform,
+		tgPlatform: context.tg_platform,
+		tgVersion: context.tg_version,
+		timezone: context.timezone,
+		timezoneOffset: context.timezone_offset,
+		colorDepth: context.color_depth,
+		touchSupport: context.touch_support,
+		country: context.country,
+		userId: context.user_id,
+		utmSource: context.utm_source,
+		utmCampaign: context.utm_campaign
+	});
+}
+async function postAnalytics(events) {
+	if (events.length === 0) return;
+	queue.push(...events);
+	return scheduleFlush();
+}
+function postEngagement(params) {
+	postAnalytics([buildEngagementEvent(params)]);
+}
+function postInteraction(params) {
+	postAnalytics([buildInteractionEvent(params)]);
+}
+function postError(params) {
+	postAnalytics([buildErrorEvent(params)]);
+}
+/**
+* Resolves once the events outstanding at call time have been sent, rather than
+* once a flush has merely been started. Two paths used to return early: a call
+* during an active flush reported a drain that had not happened, and a call
+* while the only outstanding batch was already in flight (so the queue looked
+* empty) returned before that request finished. Delegating to flushQueue makes
+* it wait for whichever drain covers the outstanding work — starting one now,
+* bypassing the timer, when nothing is running yet.
+*/
+async function flushAnalytics() {
+	return flushQueue();
+}
+
+export { flushAnalytics, postAnalytics, postEngagement, postError, postInteraction };

package/dist/api/feed.js

@@ -0,0 +1,52 @@
+import { postsV1PostServiceGetPost3, postsV1PostServiceListPosts3 } from "@rixl/sdk";
+
+// src/api/feed.ts
+function toType(type) {
+	if (type === "MEDIA_TYPE_IMAGE") return "image";
+	if (type === "MEDIA_TYPE_VIDEO") return "video";
+	return "image";
+}
+function toFeedPost(post) {
+	const withMedia = post;
+	return {
+		id: post.id ?? "",
+		feedId: post.feed_id ?? "",
+		creatorId: post.creator_id ?? "",
+		type: toType(post.type),
+		description: post.description ?? "",
+		createdAt: post.created_at ?? "",
+		image: withMedia.image,
+		video: withMedia.video
+	};
+}
+function toFeedPostsResponse(data, offset, limit) {
+	const rawTotal = data.total ?? 0;
+	return {
+		posts: (data.posts ?? []).map(toFeedPost),
+		total: typeof rawTotal === "number" ? rawTotal : Number(rawTotal),
+		offset: data.offset ?? offset,
+		limit: data.limit ?? limit
+	};
+}
+const fetchFeedPosts = async (feedId, offset = 0, limit = 10) => {
+	const { data, error, response } = await postsV1PostServiceListPosts3({
+		path: { feed_id: feedId },
+		query: {
+			"pagination.offset": offset,
+			"pagination.limit": limit
+		}
+	});
+	if (error || !data) throw new Error(`HTTP error! status: ${response?.status ?? 500}`);
+	return toFeedPostsResponse(data, offset, limit);
+};
+const fetchFeedPost = async (feedId, postId) => {
+	const { data, error, response } = await postsV1PostServiceGetPost3({ path: {
+		feed_id: feedId,
+		post_id: postId
+	} });
+	if (error) throw new Error(`HTTP error! status: ${response?.status ?? 500}`);
+	if (!data?.post) throw new Error(`HTTP error! status: 404`);
+	return toFeedPost(data.post);
+};
+
+export { fetchFeedPost, fetchFeedPosts };

package/dist/api/heatmap.d.ts

@@ -0,0 +1,6 @@
+import { VideoHeatmap } from "../types/heatmap.js";
+export interface GetVideoHeatmapOptions {
+  videoId: string;
+  buckets?: number;
+}
+export declare function getVideoHeatmap({ videoId, buckets }: GetVideoHeatmapOptions): Promise<VideoHeatmap | null>;

package/dist/api/heatmap.js

@@ -0,0 +1,28 @@
+import { analyticsV1HeatmapServiceGetVideoHeatmap } from "@rixl/sdk";
+
+// src/api/heatmap.ts
+function toNumber(value) {
+	if (value === void 0) return 0;
+	return typeof value === "number" ? value : Number(value);
+}
+function toDomainHeatmap(data) {
+	return {
+		video_id: data.video_id ?? "",
+		total_duration_ms: toNumber(data.total_duration_ms),
+		data: data.data ?? []
+	};
+}
+async function getVideoHeatmap({ videoId, buckets = 101 }) {
+	try {
+		const { data, error } = await analyticsV1HeatmapServiceGetVideoHeatmap({
+			path: { video_id: videoId },
+			query: { buckets }
+		});
+		if (error || !data) return null;
+		return toDomainHeatmap(data);
+	} catch {
+		return null;
+	}
+}
+
+export { getVideoHeatmap };

package/dist/api/hot-segments.d.ts

@@ -0,0 +1,7 @@
+import { HotSegment } from "../types/hot-segments.js";
+export interface GetHotSegmentsOptions {
+  videoId: string;
+  startDate?: string;
+  endDate?: string;
+}
+export declare function getHotSegments({ videoId, startDate, endDate }: GetHotSegmentsOptions): Promise<HotSegment[]>;

package/dist/api/hot-segments.js

@@ -0,0 +1,20 @@
+import { analyticsV1HeatmapServiceGetHotSegments } from "@rixl/sdk";
+
+// src/api/hot-segments.ts
+async function getHotSegments({ videoId, startDate, endDate }) {
+	try {
+		const query = {};
+		if (startDate) query["range.start"] = startDate;
+		if (endDate) query["range.end"] = endDate;
+		const { data, error } = await analyticsV1HeatmapServiceGetHotSegments({
+			path: { video_id: videoId },
+			query: Object.keys(query).length > 0 ? query : void 0
+		});
+		if (error) return [];
+		return data?.segments ?? [];
+	} catch {
+		return [];
+	}
+}
+
+export { getHotSegments };

package/dist/api/image.js

@@ -0,0 +1,11 @@
+import { imagesV1ImageServiceGetImage } from "@rixl/sdk";
+
+// src/api/image.ts
+const fetchImage = async (imageId) => {
+	const { data, error, response } = await imagesV1ImageServiceGetImage({ path: { image_id: imageId } });
+	if (error) throw new Error(`HTTP error! status: ${response?.status ?? 500}`);
+	if (!data?.image) throw new Error(`HTTP error! status: 404`);
+	return data.image;
+};
+
+export { fetchImage };

package/dist/api/rixl-client.d.ts

@@ -0,0 +1,3 @@
+import { AuthConfig, ConnectConfig, client } from "@rixl/sdk";
+declare function connect$1(config: ConnectConfig): Promise<string | undefined>;
+export { type AuthConfig, type ConnectConfig, connect$1 as connect };

package/dist/api/rixl-client.js

@@ -0,0 +1,14 @@
+import { initializeAnalyticsContext } from "../lib/analytics-initialize.js";
+import { client, connect } from "@rixl/sdk";
+
+// src/api/rixl-client.ts
+function getRixlClient() {
+	return client;
+}
+async function connect$1(config) {
+	const result = await connect(config);
+	initializeAnalyticsContext();
+	return result;
+}
+
+export { connect$1 as connect, getRixlClient };

package/dist/api/upload.d.ts

@@ -0,0 +1,76 @@
+export interface CreateImageUploadOptions {
+  projectId: string;
+  orgId?: string;
+  name: string;
+}
+export interface ImageUploadResult {
+  imageId: string;
+  uploadUrl: string;
+}
+export declare function createImageUpload(options: CreateImageUploadOptions): Promise<ImageUploadResult>;
+export declare function uploadImage(file: Blob | Uint8Array, options: CreateImageUploadOptions): Promise<ImageUploadResult>;
+export interface CreateVideoUploadOptions {
+  projectId: string;
+  orgId?: string;
+  name: string;
+  videoQuality?: string;
+}
+export interface VideoUploadResult {
+  videoId: string;
+  posterId: string;
+  videoUploadUrl: string;
+  posterUploadUrl: string;
+}
+export declare function createVideoUpload(options: CreateVideoUploadOptions): Promise<VideoUploadResult>;
+export declare function uploadVideo(videoFile: Blob | Uint8Array, posterFile: Blob | Uint8Array, options: CreateVideoUploadOptions): Promise<VideoUploadResult>;
+export interface AudioTrackUploadItem {
+  languageCode: string;
+  label?: string;
+  fileName: string;
+  format: string;
+  size?: number;
+}
+export interface AudioTrackUploadTarget {
+  id: string;
+  languageCode?: string;
+  uploadUrl?: string;
+}
+export interface AudioTrackUploadResult {
+  targets: AudioTrackUploadTarget[];
+}
+export declare function createAudioTrackUpload(projectId: string, videoId: string, items: AudioTrackUploadItem[]): Promise<AudioTrackUploadResult>;
+export interface SubtitleUploadItem {
+  languageCode: string;
+  label?: string;
+  fileName: string;
+  format: string;
+  size?: number;
+}
+export interface SubtitleUploadTarget {
+  id: string;
+  languageCode?: string;
+  uploadUrl?: string;
+}
+export interface SubtitleUploadResult {
+  targets: SubtitleUploadTarget[];
+}
+export declare function createSubtitleUpload(projectId: string, videoId: string, items: SubtitleUploadItem[]): Promise<SubtitleUploadResult>;
+export interface CreatePostUploadOptions {
+  projectId: string;
+  feedId: string;
+  orgId?: string;
+  creatorId: string;
+  description?: string;
+  contentType: string;
+  fileName: string;
+  videoQuality?: string;
+}
+export interface PostUploadResult {
+  postId: string;
+  contentId: string;
+  posterId: string;
+  contentUploadUrl: string;
+  posterUploadUrl: string;
+}
+export declare function uploadPost(contentFile: Blob | Uint8Array, posterFile: Blob | Uint8Array, options: CreatePostUploadOptions): Promise<PostUploadResult>;
+export declare function createPostUpload(options: CreatePostUploadOptions): Promise<PostUploadResult>;