vp-cw (Continue Watching)

vp-cw is a lightweight TypeScript library for tracking and persisting video watch progress across sessions and devices. It’s designed for video platforms and players that want a simple, flexible "Continue Watching" SDK.

Features

• Save and restore progress per user/asset
• Prevent regressions by default (no lower overwrites)
• Reset progress when needed
• In‑memory cache to cut redundant requests
• Built‑in health check with retry logic
• Timeout‑aware requests (avoid hanging fetches)
• TypeScript types, ESM/CJS/UMD builds

Installation

npm install vp-cw

Quick Start

import ContinueWatching from "vp-cw";

const cw = new ContinueWatching({
  apiEndpoint: "https://your-api.com/continue-watching", // required
});

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

// Get single asset’s position
const [single] = await cw.getWatchTimes("user-123", "video-456");
const position = single ? Number(single.position) : 0;

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

// Reset a specific asset
await cw.resetAssetPosition("user-123", "video-456");

Browser/UMD usage:

<script src="./dist/index.umd.js"></script>
<script>
  const cw = new ContinueWatching({ apiEndpoint: "https://your-api.com/continue-watching" });
  // Same API as above
  cw.saveWatchTime("user-123", "video-456", 120);
</script>

API Reference

• new ContinueWatching({ apiEndpoint })

  • apiEndpoint (string): Base URL for your backend endpoint.
  • Note: Internal connectionRetryCount defaults to 5.

• saveWatchTime(userId, assetId, watchTime, allowLowering = false) → Promise<{ success: boolean; reason?: string }>

  • Saves the watch time. By default, lower times are not saved unless allowLowering is true.

• getWatchTimes(userId, assetId?) → Promise<Asset[]>

  • With assetId, returns an array with a single Asset (or empty if none).
  • Without assetId, returns an array of all watched assets for the user.

• resetAssetPosition(userId, assetId) → Promise<{ success: boolean; reason?: string } | void>

  • Resets a user’s position for the asset to 0.

• findAsset(userId, assetId) → Asset | undefined

  • Looks up a single asset in the in‑memory cache.

Types

interface ContinueWatchingConfig {
  apiEndpoint: string;
  connectionRetryCount: number; // internal default is 5
}

interface Asset {
  assetId: string;
  position: string; // seconds as string
}

Backend Contract

The library expects the following endpoints relative to apiEndpoint:

• GET /health → 200 OK if service is healthy
• GET /:userId → Asset[]
• GET /:userId/:assetId → number (position in seconds)
• POST /:userId/:assetId/:position → save position

Notes:

• For a single asset, the API returns a number. The SDK normalizes that into an Asset[] with one item.
• The SDK prevents lowering previously stored positions unless allowLowering = true is passed to saveWatchTime.

Development

• npm run dev: Build in watch mode
• npm run build: Produce CJS/ESM/UMD bundles in dist/
• npm test: Run tests

The test page index.html loads the UMD bundle from dist/ for quick manual verification.