@meshstream/p2p-web 0.2.1 → 1.0.1

package/README.md

@@ -1,12 +1,15 @@
-# MeshStream P2P Web SDK
-
-Browser HLS and DASH P2P delivery SDK for MeshStream P2P-CDN. The SDK wraps
-`hls.js`, Shaka Player, and `p2p-media-loader`, fetches runtime configuration
-from Config API, joins a WebRTC tracker swarm, reports playback/P2P statistics,
-and keeps CDN playback as the fallback path.
-
-## Install
-
+# MeshStream P2P Web SDK
+
+SDK-owned console diagnostics respect the client `logLevel` (default `none`), with redaction and
+repeated-error limiting. Web does not write local log files. See the [logging guide](../../docs/sdk-logging.md).
+
+Browser HLS and DASH P2P delivery SDK for MeshStream P2P-CDN. The SDK wraps
+`hls.js`, Shaka Player, and `p2p-media-loader`, fetches runtime configuration
+from Config API, joins a WebRTC tracker swarm, reports playback/P2P statistics,
+and keeps CDN playback as the fallback path.
+
+## Install
+
 ```bash
 # SDK-managed player: MeshStream bundles its HLS, DASH, and P2P runtimes.
 npm install @meshstream/p2p-web
@@ -19,33 +22,33 @@ over its configuration or lifecycle:
 ```bash
 npm install @meshstream/p2p-web hls.js
 ```
-
-In this monorepo the SDK is consumed as a workspace package:
-
-```bash
-npm run build:web-sdk
-npm run build -w @p2pcdn/web-demo
-```
-
-## Quick Start
-
-```ts
+
+In this monorepo the SDK is consumed as a workspace package:
+
+```bash
+npm run build:web-sdk
+npm run build -w @p2pcdn/web-demo
+```
+
+## Quick Start
+
+```ts
 import { attach } from "@meshstream/p2p-web";
 
 const player = attach({
-  key: "your_sdk_key",
+  key: "your_sdk_key",
   url: "https://cdn.example.com/live/index.m3u8", // or .mpd / .mp4 / .mp3
   video: document.querySelector("video"),
-});
-
-await player.start();
-
+});
+
+await player.start();
+
 window.addEventListener("pagehide", () => player.dispose(), { once: true });
 ```
 
 The historic `video` option accepts any `HTMLMediaElement`; pass an `<audio>`
 element for progressive MP3 playback.
-
+
 The SDK fetches SaaS bootstrap configuration, selects trackers/reporting
 endpoints, detects browser capability, starts WebRTC P2P when possible, and
 keeps CDN playback as the automatic fallback path.
@@ -172,8 +175,8 @@ import it from `@meshstream/p2p-web/advanced`; standard integrations should
 continue to use root-level `attach`.
 
 For a plain video element:
-
-```ts
+
+```ts
 import { attach } from "@meshstream/p2p-web";
 
 const player = attach({ key, url, video });
@@ -214,13 +217,13 @@ window.addEventListener("pagehide", () => {
 
 For rotating signed URLs, pass a stable business identity so viewers join the
 same swarm. `mimeType` is useful when the media URL has no `.m3u8`, `.mpd`, `.mp4`, or `.mp3`
-suffix. `originHeaders` are sent only to same-origin manifest, segment, and key requests on the
-configured media origin. SDK-controlled headers such as `Range` and hop-by-hop headers are ignored;
-the browser still applies its own forbidden-header and CORS rules. For Shaka and dash.js
-adapter objects, the player must expose its request interception API; otherwise
-the SDK fails explicitly instead of starting without the requested headers.
-
-```ts
+suffix. `originHeaders` are sent only to same-origin manifest, segment, and key requests on the
+configured media origin. SDK-controlled headers such as `Range` and hop-by-hop headers are ignored;
+the browser still applies its own forbidden-header and CORS rules. For Shaka and dash.js
+adapter objects, the player must expose its request interception API; otherwise
+the SDK fails explicitly instead of starting without the requested headers.
+
+```ts
 const player = attach({
   key,
   url: signedManifestUrl,
@@ -250,17 +253,17 @@ const player = attach({
     kind === "segment" ? { Authorization: `Bearer ${playbackToken}` } : undefined,
 });
 ```
-
+
 For Video.js:
-
-```ts
+
+```ts
 import { attachToVideoJs } from "@meshstream/p2p-web/adapters";
-
+
 const player = attachToVideoJs({
-  key,
-  url,
-  player: videojs("player"),
-});
+  key,
+  url,
+  player: videojs("player"),
+});
 await player.start();
 ```
 
@@ -288,48 +291,48 @@ await session.start();
 ```
 
 For players built on top of a standard `<video>` element:
-
-```ts
+
+```ts
 import { attachToArtPlayer, attachToDPlayer, attachToPlyr } from "@meshstream/p2p-web/adapters";
-
-await attachToPlyr({ key, url, player: plyr }).start();
-await attachToDPlayer({ key, url, player: dplayer }).start();
-await attachToArtPlayer({ key, url, player: art }).start();
-```
-
+
+await attachToPlyr({ key, url, player: plyr }).start();
+await attachToDPlayer({ key, url, player: dplayer }).start();
+await attachToArtPlayer({ key, url, player: art }).start();
+```
+
 The named adapters resolve common `video` or `media` fields, or a `<video>` nested
 inside the player's root element, and then use the
 same automatic HLS, DASH, and progressive-media path as the plain video adapter. They are media-element bridges,
 not native Video.js, Plyr, DPlayer, or ArtPlayer engine plugins: MeshStream
 owns the playback instance used for the supplied media element.
-
-For DASH with the standard SDK path:
-
-```ts
+
+For DASH with the standard SDK path:
+
+```ts
 import { attach } from "@meshstream/p2p-web";
 
 const player = attach({
-  key,
-  url: "https://cdn.example.com/live/index.mpd",
-  video,
-});
-await player.start();
-```
-
+  key,
+  url: "https://cdn.example.com/live/index.mpd",
+  video,
+});
+await player.start();
+```
+
 `attach` selects DASH for `.mpd` URLs and HLS for `.m3u8` URLs. Customers
-do not pass a protocol flag. DASH P2P uses Shaka Player internally for the
-standard SDK path.
-
-For an existing Shaka Player:
-
-```ts
+do not pass a protocol flag. DASH P2P uses Shaka Player internally for the
+standard SDK path.
+
+For an existing Shaka Player:
+
+```ts
 import { attachToShaka } from "@meshstream/p2p-web/adapters";
-
-const player = attachToShaka({
-  key,
-  url: "https://cdn.example.com/live/index.mpd",
-  player: shakaPlayer,
-});
+
+const player = attachToShaka({
+  key,
+  url: "https://cdn.example.com/live/index.mpd",
+  player: shakaPlayer,
+});
 await player.start();
 ```
 
@@ -338,10 +341,10 @@ application retains ownership of the supplied Shaka instance and must destroy
 it when appropriate.
 
 For an existing dash.js player:
-
-```ts
+
+```ts
 import { attachToDashJs } from "@meshstream/p2p-web/adapters";
-
+
 const player = attachToDashJs({
   key,
   url: "https://cdn.example.com/live/index.mpd",
@@ -392,29 +395,29 @@ audio/video fallback requests retain those headers; dynamic values override
 static values. Cross-origin media, text, DRM, non-contiguous ranges, and
 RxPlayer low-latency chunked loading remain on the customer's RxPlayer/CDN
 path without SDK-supplied headers.
-
-Telemetry keeps the playback host and path for diagnostics but strips query and fragment data,
-so signed playback credentials are not included in reports.
-
-## Runtime Contract
-
-- `key` is the customer-facing SDK Key and can be embedded in Web pages.
+
+Telemetry keeps the playback host and path for diagnostics but strips query and fragment data,
+so signed playback credentials are not included in reports.
+
+## Runtime Contract
+
+- `key` is the customer-facing SDK Key and can be embedded in Web pages.
 - `homeRegion` is resolved from the SDK Key and identifies the tenant's registered data-home
   region. It is returned by bootstrap for diagnostics and future regional routing; customer code
   cannot override it.
 - Request-network GeoIP is used only for access-side Tracker/ICE locality and is not a data-residency
   selection.
-- Customer integrations should only need `key`, the media `url`, and a `video`
-  element for the standard Web path.
-- The SaaS bootstrap endpoint, tracker pool, ICE servers, reporting route, and
-  scheduling policy are internal service configuration.
-- P2P, tracker, authorization, and reporting failures must not block `hls.js`
-  playback.
-- `detectWebP2pCapability` should be called before constructing the P2P client.
-  iOS Safari HLS without MSE is routed to native HLS CDN playback.
-- Fallback reporting uses the service-owned endpoint returned by bootstrap.
-- Signed CDN URL query fields such as `token`, `signature`, `expires`,
-  `x-amz-*`, `x-oss-*`, and `x-goog-*` are excluded from URL-derived swarm IDs.
+- Customer integrations should only need `key`, the media `url`, and a `video`
+  element for the standard Web path.
+- The SaaS bootstrap endpoint, tracker pool, ICE servers, reporting route, and
+  scheduling policy are internal service configuration.
+- P2P, tracker, authorization, and reporting failures must not block `hls.js`
+  playback.
+- `detectWebP2pCapability` should be called before constructing the P2P client.
+  iOS Safari HLS without MSE is routed to native HLS CDN playback.
+- Fallback reporting uses the service-owned endpoint returned by bootstrap.
+- Signed CDN URL query fields such as `token`, `signature`, `expires`,
+  `x-amz-*`, `x-oss-*`, and `x-goog-*` are excluded from URL-derived swarm IDs.
 - `contentId` is optional. When supplied, the SDK derives the internal swarm ID
   from it so rotating signed URL paths remain in the same swarm; otherwise it
   derives identity from the canonical playback URL.
@@ -431,17 +434,17 @@ so signed playback credentials are not included in reports.
   `Accept-Ranges` through CORS, and allow `GET`, `HEAD`, `OPTIONS`, and the `Range` request header.
   `HEAD` is recommended; if the origin explicitly returns `405` or `501`, extensionless URL detection
   uses a one-byte range `GET` instead. Missing metadata or any P2P error falls back to the original CDN URL.
-
-## Public API
-
-```ts
+
+## Public API
+
+```ts
 // Standard customer-facing entry point
 attach(options)
 
 // Advanced player adapters
 import { attachToShaka, attachToDashJs, attachToVhs, attachToVideoJs } from "@meshstream/p2p-web/adapters";
-
-// P2P runtime controls
+
+// P2P runtime controls
 player.start()
 player.dispose()
 player.setP2pEnabled(enabled)
@@ -480,15 +483,15 @@ Low-latency HLS/DASH partial CMAF segment requests remain on the player CDN
 path. P2P only distributes complete segments: sharing a response before its
 partial body is complete breaks player cancellation semantics and causes
 latency jitter. Playback continues normally through CDN for those parts.
-
-## Release Checks
-
-```bash
-npm test -w @meshstream/p2p-web
-npm run build:web-sdk:release
-npm run pack:dry-run -w @meshstream/p2p-web
-```
-
+
+## Release Checks
+
+```bash
+npm test -w @meshstream/p2p-web
+npm run build:web-sdk:release
+npm run pack:dry-run -w @meshstream/p2p-web
+```
+
 `prepack` runs the SDK test suite, bundles the runtime dependencies into the
 public entry points, and then minifies the release output before package
 creation. The published package contains only bundled JavaScript, `.d.ts`