react-native-meshstream 0.0.0-stage → 1.0.2

package/lib/typescript/types.d.ts

@@ -0,0 +1,87 @@
+export type MeshStreamMimeType = 'm3u8' | 'mpd' | 'mp4' | 'mp3';
+/** A client can own multiple independent playback sessions. */
+export interface MeshStreamConfig {
+    key: string;
+    p2pEnabled?: boolean;
+}
+/** Versions of the JavaScript wrapper and native engine used by this application. */
+export interface MeshStreamVersionInfo {
+    /** Version of the installed react-native-meshstream package. */
+    packageVersion: string;
+    /** Version of the Android or Apple MeshStream engine loaded by the bridge. */
+    nativeSdkVersion: string;
+    /** Native platform that supplied nativeSdkVersion. */
+    platform: 'android' | 'ios';
+}
+export interface PlaybackSessionOptions {
+    url: string;
+    contentId?: string;
+    mimeType?: MeshStreamMimeType;
+    originHeaders?: Record<string, string>;
+}
+export type MeshStreamPlaybackMode = 'NATIVE_P2P' | 'NATIVE_CDN';
+export type MeshStreamUnavailableReason = 'OK' | 'ACCOUNT_DISABLED' | 'APP_DISABLED' | 'APP_NOT_FOUND' | 'KEY_DISABLED' | 'PLATFORM_DISABLED' | 'ORIGIN_DENIED' | 'PACKAGE_DENIED' | 'BUNDLE_DENIED' | 'SIGNING_CERT_DENIED' | 'TEAM_DENIED' | 'AUTH_FAILED' | 'CONFIG_UNAVAILABLE' | 'TRACKER_ERROR' | 'NO_PEERS' | 'UNSUPPORTED' | 'INITIALIZATION_FAILED' | 'DISABLED' | 'KEY_P2P_DISABLED' | 'QUOTA_EXHAUSTED' | 'QUOTA_DISABLED';
+export interface MeshStreamStatus {
+    accountEnabled: boolean;
+    applicationEnabled: boolean;
+    keyEnabled: boolean;
+    platformEnabled: boolean;
+    effectiveP2pEnabled: boolean;
+    reason: MeshStreamUnavailableReason;
+    configVersion?: string;
+    edgeRegion?: string;
+    quotaStatus?: string;
+    trackerPoolReady?: boolean;
+}
+export interface MeshStreamStats {
+    httpDownloaded: number;
+    p2pDownloaded: number;
+    p2pUploaded: number;
+    httpSegmentDownloadSuccesses: number;
+    httpSegmentDownloadFailures: number;
+    p2pSegmentDownloadSuccesses: number;
+    p2pSegmentDownloadFailures: number;
+    p2pSegmentUploadSuccesses: number;
+    p2pSegmentUploadFailures: number;
+    connectedPeers: number;
+    peerConnectErrors: number;
+    trackerErrors: number;
+    downloadOffloadRatio: number;
+    p2pSegmentDownloadSuccessRatio: number;
+    p2pSegmentUploadSuccessRatio: number;
+}
+export interface MeshStreamColdStartSnapshot {
+    p2pDownloaded: number;
+    httpDownloaded: number;
+}
+export interface MeshStreamDiagnostics {
+    fallbackCount: number;
+    firstPeerConnectMs?: number;
+    coldStart?: MeshStreamColdStartSnapshot;
+    lastTrackerError?: string;
+    lastPeerError?: string;
+    lastErrorAtMs?: number;
+    iceAttempts: number;
+    iceSuccesses: number;
+    iceFailures: number;
+    iceDurationMs: number;
+}
+export interface MeshStreamSessionInfo {
+    clientId: string;
+    sessionId: string;
+    playbackUrl: string;
+    playbackMode: MeshStreamPlaybackMode;
+    fallbackReason?: MeshStreamUnavailableReason;
+}
+export type MeshStreamEventName = 'peerCountChanged' | 'playbackPrepared' | 'p2pReady' | 'p2pUnavailable' | 'statistics' | 'cdnFallback' | 'trackerError' | 'peerConnectError';
+export interface MeshStreamEvent {
+    type: MeshStreamEventName;
+    clientId: string;
+    sessionId: string;
+    peerCount?: number;
+    playbackUrl?: string;
+    reason?: MeshStreamUnavailableReason;
+    statistics?: MeshStreamStats;
+    bytes?: number;
+    totalErrors?: number;
+}

package/lib/typescript/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/typescript/version.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Public npm package version. Keep this value aligned with package.json for each release.
+ * It is deliberately separate from the Android/iOS engine version.
+ */
+export declare const MESHSTREAM_REACT_NATIVE_VERSION = "1.0.2";

package/lib/typescript/version.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MESHSTREAM_REACT_NATIVE_VERSION = void 0;
+/**
+ * Public npm package version. Keep this value aligned with package.json for each release.
+ * It is deliberately separate from the Android/iOS engine version.
+ */
+exports.MESHSTREAM_REACT_NATIVE_VERSION = '1.0.2';

package/package.json

@@ -1,6 +1,54 @@
 {
   "name": "react-native-meshstream",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.2",
+  "description": "MeshStream P2P playback URL SDK for React Native",
+  "main": "lib/typescript/index.js",
+  "module": "lib/typescript/index.js",
+  "types": "lib/typescript/index.d.ts",
+  "react-native": "src/index.ts",
+  "files": [
+    "src",
+    "lib",
+    "android/build.gradle",
+    "android/src",
+    "ios",
+    "react-native.config.js",
+    "tests/ios",
+    "MeshStreamP2P.podspec",
+    "README.md",
+    "README.zh-CN.md",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "build": "tsc --project tsconfig.json",
+    "typecheck": "tsc --project tsconfig.json --noEmit",
+    "verify:version": "node scripts/verify-package-version.mjs",
+    "test:ios": "node --test tests/node/ios-regression-guards.test.mjs",
+    "verify:ios": "npm run test:ios && node scripts/verify-ios-package.mjs && node scripts/verify-ios-xctest.mjs",
+    "verify:ios:public": "npm run test:ios && node scripts/verify-ios-package.mjs && node scripts/verify-ios-xctest.mjs --repo-update",
+    "prepare": "npm run build",
+    "prepack": "npm run verify:version",
+    "test": "npm run build && node --test tests/node/*.test.mjs"
+  },
+  "keywords": [
+    "react-native",
+    "p2p",
+    "cdn",
+    "video",
+    "meshstream"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Mesh-Stream/meshstream-p2p-react-native-sdk.git"
+  },
+  "license": "Apache-2.0",
+  "peerDependencies": {
+    "react": ">=18.0.0",
+    "react-native": ">=0.72.0"
+  },
+  "devDependencies": {
+    "@types/react": "^18.3.0",
+    "react-native": "^0.76.0",
+    "typescript": "^5.6.3"
+  }
+}

package/react-native.config.js

@@ -0,0 +1,11 @@
+module.exports = {
+  dependency: {
+    platforms: {
+      android: {
+        sourceDir: './android',
+        packageImportPath: 'import net.meshstream.reactnative.MeshStreamP2PPackage;',
+        packageInstance: 'new MeshStreamP2PPackage()',
+      },
+    },
+  },
+};

package/src/NativeMeshStreamP2P.ts

@@ -0,0 +1,36 @@
+import { NativeModules } from 'react-native';
+
+import type {
+  MeshStreamConfig,
+  MeshStreamDiagnostics,
+  MeshStreamSessionInfo,
+  MeshStreamStats,
+  MeshStreamStatus,
+  PlaybackSessionOptions,
+} from './types';
+
+interface NativeMeshStreamP2P {
+  getSdkVersion(): Promise<string>;
+  createClient(config: MeshStreamConfig): Promise<{ clientId: string; status: MeshStreamStatus }>;
+  createPlaybackSession(clientId: string, options: PlaybackSessionOptions): Promise<MeshStreamSessionInfo>;
+  preload(clientId: string, sessionId: string): Promise<boolean>;
+  setP2pEnabled(clientId: string, sessionId: string, enabled: boolean): Promise<void>;
+  updateBufferedDurationMs(clientId: string, sessionId: string, durationMs: number): Promise<void>;
+  updateCurrentPositionMs(clientId: string, sessionId: string, positionMs: number): Promise<void>;
+  getStats(clientId: string, sessionId: string): Promise<MeshStreamStats>;
+  getDiagnostics(clientId: string, sessionId: string): Promise<MeshStreamDiagnostics>;
+  getStatus(clientId: string): Promise<MeshStreamStatus>;
+  closeSession(clientId: string, sessionId: string): Promise<void>;
+  closeClient(clientId: string): Promise<void>;
+}
+
+const nativeModule = NativeModules.MeshStreamP2P as NativeMeshStreamP2P | undefined;
+
+export function requireNativeModule(): NativeMeshStreamP2P {
+  if (!nativeModule) {
+    throw new Error(
+      'MeshStreamP2P is not linked. Rebuild the iOS or Android app after installing react-native-meshstream.',
+    );
+  }
+  return nativeModule;
+}

package/src/index.ts

@@ -0,0 +1,176 @@
+import { DeviceEventEmitter, Platform, type EmitterSubscription } from 'react-native';
+
+import { requireNativeModule } from './NativeMeshStreamP2P';
+import { MESHSTREAM_REACT_NATIVE_VERSION } from './version';
+import type {
+  MeshStreamConfig,
+  MeshStreamDiagnostics,
+  MeshStreamEvent,
+  MeshStreamEventName,
+  MeshStreamSessionInfo,
+  MeshStreamStats,
+  MeshStreamStatus,
+  MeshStreamVersionInfo,
+  PlaybackSessionOptions,
+} from './types';
+
+export * from './types';
+
+const EVENT_NAME = 'MeshStreamP2P:event';
+
+function assertNonEmpty(value: string | undefined, field: string): asserts value is string {
+  if (!value?.trim()) throw new Error(`${field} must not be empty.`);
+}
+
+function assertNonNegative(value: number, field: string): void {
+  if (!Number.isFinite(value) || value < 0) throw new Error(`${field} must be a finite non-negative number.`);
+}
+
+export class MeshStreamPlaybackSession {
+  readonly clientId: string;
+  readonly sessionId: string;
+  readonly playbackUrl: string;
+  readonly playbackMode: MeshStreamSessionInfo['playbackMode'];
+  readonly fallbackReason?: MeshStreamSessionInfo['fallbackReason'];
+  private readonly isClientClosed: () => boolean;
+  private closed = false;
+  private closing?: Promise<void>;
+
+  constructor(info: MeshStreamSessionInfo, isClientClosed: () => boolean = () => false) {
+    this.clientId = info.clientId;
+    this.sessionId = info.sessionId;
+    this.playbackUrl = info.playbackUrl;
+    this.playbackMode = info.playbackMode;
+    this.fallbackReason = info.fallbackReason;
+    this.isClientClosed = isClientClosed;
+  }
+
+  async preload(): Promise<boolean> {
+    return this.withOpen(() => requireNativeModule().preload(this.clientId, this.sessionId));
+  }
+
+  async setP2pEnabled(enabled: boolean): Promise<void> {
+    return this.withOpen(() => requireNativeModule().setP2pEnabled(this.clientId, this.sessionId, enabled));
+  }
+
+  async updateBufferedDurationMs(durationMs: number): Promise<void> {
+    assertNonNegative(durationMs, 'durationMs');
+    return this.withOpen(() => requireNativeModule().updateBufferedDurationMs(this.clientId, this.sessionId, durationMs));
+  }
+
+  async updateCurrentPositionMs(positionMs: number): Promise<void> {
+    assertNonNegative(positionMs, 'positionMs');
+    return this.withOpen(() => requireNativeModule().updateCurrentPositionMs(this.clientId, this.sessionId, positionMs));
+  }
+
+  async getStats(): Promise<MeshStreamStats> {
+    return this.withOpen(() => requireNativeModule().getStats(this.clientId, this.sessionId));
+  }
+
+  async getDiagnostics(): Promise<MeshStreamDiagnostics> {
+    return this.withOpen(() => requireNativeModule().getDiagnostics(this.clientId, this.sessionId));
+  }
+
+  async close(): Promise<void> {
+    if (this.closed) return;
+    if (this.isClientClosed()) {
+      return;
+    }
+    if (!this.closing) {
+      this.closing = requireNativeModule()
+        .closeSession(this.clientId, this.sessionId)
+        .then(() => { this.closed = true; })
+        .finally(() => { this.closing = undefined; });
+    }
+    return this.closing;
+  }
+
+  private async withOpen<T>(operation: () => Promise<T>): Promise<T> {
+    if (this.closed || this.closing || this.isClientClosed()) {
+      throw new Error('Playback session is closed.');
+    }
+    return operation();
+  }
+}
+
+export class MeshStreamClient {
+  readonly clientId: string;
+  private closed = false;
+  private closing?: Promise<void>;
+
+  constructor(clientId: string) {
+    this.clientId = clientId;
+  }
+
+  async createPlaybackSession(options: PlaybackSessionOptions): Promise<MeshStreamPlaybackSession> {
+    assertNonEmpty(options.url, 'options.url');
+    return this.withOpen(async () => {
+      const info = await requireNativeModule().createPlaybackSession(this.clientId, options);
+      if (this.closed || this.closing) throw new Error('MeshStream client is closed.');
+      return new MeshStreamPlaybackSession(info, () => this.closed || this.closing !== undefined);
+    });
+  }
+
+  async getStatus(): Promise<MeshStreamStatus> {
+    return this.withOpen(() => requireNativeModule().getStatus(this.clientId));
+  }
+
+  async close(): Promise<void> {
+    if (this.closed) return;
+    if (!this.closing) {
+      this.closing = requireNativeModule()
+        .closeClient(this.clientId)
+        .then(() => { this.closed = true; })
+        .finally(() => { this.closing = undefined; });
+    }
+    return this.closing;
+  }
+
+  private async withOpen<T>(operation: () => Promise<T>): Promise<T> {
+    if (this.closed || this.closing) throw new Error('MeshStream client is closed.');
+    return operation();
+  }
+}
+
+export const MeshStream = {
+  /** Returns the version of the native MeshStream SDK loaded by this application. */
+  async getSdkVersion(): Promise<string> {
+    return requireNativeModule().getSdkVersion();
+  },
+
+  /** Returns the React Native package version and the loaded native engine version. */
+  async getVersion(): Promise<MeshStreamVersionInfo> {
+    const platform = Platform.OS;
+    if (platform !== 'android' && platform !== 'ios') {
+      throw new Error(`react-native-meshstream does not support ${platform}.`);
+    }
+    return {
+      packageVersion: MESHSTREAM_REACT_NATIVE_VERSION,
+      nativeSdkVersion: await MeshStream.getSdkVersion(),
+      platform,
+    };
+  },
+
+  async create(config: MeshStreamConfig): Promise<MeshStreamClient> {
+    assertNonEmpty(config.key, 'config.key');
+    const result = await requireNativeModule().createClient(config);
+    return new MeshStreamClient(result.clientId);
+  },
+
+  addEventListener(listener: (event: MeshStreamEvent) => void): EmitterSubscription {
+    return DeviceEventEmitter.addListener(EVENT_NAME, listener);
+  },
+};
+
+/** Filtered event subscription for a particular client or playback session. */
+export function addMeshStreamEventListener(
+  listener: (event: MeshStreamEvent) => void,
+  filter?: { clientId?: string; sessionId?: string; type?: MeshStreamEventName },
+): EmitterSubscription {
+  return MeshStream.addEventListener((event) => {
+    if (filter?.clientId && event.clientId !== filter.clientId) return;
+    if (filter?.sessionId && event.sessionId !== filter.sessionId) return;
+    if (filter?.type && event.type !== filter.type) return;
+    listener(event);
+  });
+}

package/src/types.ts

@@ -0,0 +1,128 @@
+export type MeshStreamMimeType = 'm3u8' | 'mpd' | 'mp4' | 'mp3';
+
+/** A client can own multiple independent playback sessions. */
+export interface MeshStreamConfig {
+  key: string;
+  p2pEnabled?: boolean;
+}
+
+/** Versions of the JavaScript wrapper and native engine used by this application. */
+export interface MeshStreamVersionInfo {
+  /** Version of the installed react-native-meshstream package. */
+  packageVersion: string;
+  /** Version of the Android or Apple MeshStream engine loaded by the bridge. */
+  nativeSdkVersion: string;
+  /** Native platform that supplied nativeSdkVersion. */
+  platform: 'android' | 'ios';
+}
+
+export interface PlaybackSessionOptions {
+  url: string;
+  contentId?: string;
+  mimeType?: MeshStreamMimeType;
+  originHeaders?: Record<string, string>;
+}
+
+export type MeshStreamPlaybackMode = 'NATIVE_P2P' | 'NATIVE_CDN';
+
+export type MeshStreamUnavailableReason =
+  | 'OK'
+  | 'ACCOUNT_DISABLED'
+  | 'APP_DISABLED'
+  | 'APP_NOT_FOUND'
+  | 'KEY_DISABLED'
+  | 'PLATFORM_DISABLED'
+  | 'ORIGIN_DENIED'
+  | 'PACKAGE_DENIED'
+  | 'BUNDLE_DENIED'
+  | 'SIGNING_CERT_DENIED'
+  | 'TEAM_DENIED'
+  | 'AUTH_FAILED'
+  | 'CONFIG_UNAVAILABLE'
+  | 'TRACKER_ERROR'
+  | 'NO_PEERS'
+  | 'UNSUPPORTED'
+  | 'INITIALIZATION_FAILED'
+  | 'DISABLED'
+  | 'KEY_P2P_DISABLED'
+  | 'QUOTA_EXHAUSTED'
+  | 'QUOTA_DISABLED';
+
+export interface MeshStreamStatus {
+  accountEnabled: boolean;
+  applicationEnabled: boolean;
+  keyEnabled: boolean;
+  platformEnabled: boolean;
+  effectiveP2pEnabled: boolean;
+  reason: MeshStreamUnavailableReason;
+  configVersion?: string;
+  edgeRegion?: string;
+  quotaStatus?: string;
+  trackerPoolReady?: boolean;
+}
+
+export interface MeshStreamStats {
+  httpDownloaded: number;
+  p2pDownloaded: number;
+  p2pUploaded: number;
+  httpSegmentDownloadSuccesses: number;
+  httpSegmentDownloadFailures: number;
+  p2pSegmentDownloadSuccesses: number;
+  p2pSegmentDownloadFailures: number;
+  p2pSegmentUploadSuccesses: number;
+  p2pSegmentUploadFailures: number;
+  connectedPeers: number;
+  peerConnectErrors: number;
+  trackerErrors: number;
+  downloadOffloadRatio: number;
+  p2pSegmentDownloadSuccessRatio: number;
+  p2pSegmentUploadSuccessRatio: number;
+}
+
+export interface MeshStreamColdStartSnapshot {
+  p2pDownloaded: number;
+  httpDownloaded: number;
+}
+
+export interface MeshStreamDiagnostics {
+  fallbackCount: number;
+  firstPeerConnectMs?: number;
+  coldStart?: MeshStreamColdStartSnapshot;
+  lastTrackerError?: string;
+  lastPeerError?: string;
+  lastErrorAtMs?: number;
+  iceAttempts: number;
+  iceSuccesses: number;
+  iceFailures: number;
+  iceDurationMs: number;
+}
+
+export interface MeshStreamSessionInfo {
+  clientId: string;
+  sessionId: string;
+  playbackUrl: string;
+  playbackMode: MeshStreamPlaybackMode;
+  fallbackReason?: MeshStreamUnavailableReason;
+}
+
+export type MeshStreamEventName =
+  | 'peerCountChanged'
+  | 'playbackPrepared'
+  | 'p2pReady'
+  | 'p2pUnavailable'
+  | 'statistics'
+  | 'cdnFallback'
+  | 'trackerError'
+  | 'peerConnectError';
+
+export interface MeshStreamEvent {
+  type: MeshStreamEventName;
+  clientId: string;
+  sessionId: string;
+  peerCount?: number;
+  playbackUrl?: string;
+  reason?: MeshStreamUnavailableReason;
+  statistics?: MeshStreamStats;
+  bytes?: number;
+  totalErrors?: number;
+}

package/src/version.ts

@@ -0,0 +1,5 @@
+/**
+ * Public npm package version. Keep this value aligned with package.json for each release.
+ * It is deliberately separate from the Android/iOS engine version.
+ */
+export const MESHSTREAM_REACT_NATIVE_VERSION = '1.0.2';

package/tests/ios/MeshStreamP2PValidationTests.m

@@ -0,0 +1,35 @@
+#import <XCTest/XCTest.h>
+#import <MeshStreamKit/MeshStreamKit.h>
+
+#import "../../ios/MeshStreamP2PValidation.h"
+
+@interface MeshStreamP2PValidationTests : XCTestCase
+@end
+
+@implementation MeshStreamP2PValidationTests
+
+- (void)testNativeVersionIsAvailableBeforeCreatingClient {
+    XCTAssertEqualObjects([P2PSDK getSdkVersion], @"1.0.6");
+}
+
+- (void)testTrimsURLsAndFiltersNonStringHeaders {
+    XCTAssertEqualObjects(
+        MeshStreamTrimmedString(@"  content-42\n"),
+        @"content-42");
+    XCTAssertNil(MeshStreamTrimmedString(@42));
+    XCTAssertEqualObjects(
+        MeshStreamHTTPURLFromValue(@" https://example.com/live.m3u8 ").absoluteString,
+        @"https://example.com/live.m3u8");
+    XCTAssertNil(MeshStreamHTTPURLFromValue(@"ftp://example.com/live.m3u8"));
+    NSDictionary *headers = MeshStreamStringHeaders(@{
+        @"Authorization": @"Bearer token",
+        @"retry": @1,
+        @2: @"ignored",
+    });
+    NSDictionary *expectedHeaders = @{
+        @"Authorization": @"Bearer token",
+    };
+    XCTAssertEqualObjects(headers, expectedHeaders);
+}
+
+@end