vp-cw

vp-cw (Continue Watching)

Vp-cw is a lightweight TypeScript library for tracking and persisting video watch progress across sessions and devices. Designed for video platforms and players that want to implement "Continue Watching" functionality with minimal setup and maximum flexibility.

---

Features

• Save and restore watch progress per user and asset
• Prevent regressions (don't overwrite with lower watch times)
• Optionally reset progress
• In-memory cache to reduce redundant API calls
• Fully typed and extensible (written in TypeScript)
• Simple REST API integration

---

Installation

npm install vp-cw

---

Usage

import ContinueWatching from "vp-cw";

const cw = new ContinueWatching({
	apiEndpoint: "https://your-api.com/continue-watching", // Required
	watchThreshold: 0.9, // optional, default: 0.9 (90%)
});

// Save watch time
await cw.saveWatchTime("user-123", "video-456", 120);

// Get watch time
const watchTime = await cw.getWatchTimes("user-123", "video-456");

// Reset watch time
await cw.resetAssetPosition("user-123", "video-456");

// Get all watched assets
const assets = await cw.getWatchTimes("user-123");

---

API

new ContinueWatching(config)

• apiEndpoint (string): Base URL of your backend endpoint.
• watchThreshold (number): A float (e.g., 0.9) representing when a video should be marked as watched.

.saveWatchTime(userId, assetId, watchTime, allowLowering = false)

Saves the user's watch time for an asset. Will not overwrite a higher value unless allowLowering is true.

.getWatchTimes(userId, assetId?)

• With assetId: returns number (watch time in seconds)
• Without assetId: returns Asset[] (list of watched items)

.resetAssetPosition(userId, assetId)

Sets a user's watch time for the asset back to 0.

---

Types

interface ContinueWatchingConfig {
	apiEndpoint: string;
	watchThreshold: number;
}

interface Asset {
	assetId: string;
	position: string; // stringified number in seconds
}

---

Example API Endpoints

• GET /:userId → Asset[]
• GET /:userId/:assetId → number
• POST /:userId/:assetId/:position → Save position