react-native-meshstream 0.0.0-stage → 1.0.0

package/package.json

@@ -1,6 +1,51 @@
 {
   "name": "react-native-meshstream",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "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",
+    "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"
+  },
+  "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,35 @@
+import { NativeModules } from 'react-native';
+
+import type {
+  MeshStreamConfig,
+  MeshStreamDiagnostics,
+  MeshStreamSessionInfo,
+  MeshStreamStats,
+  MeshStreamStatus,
+  PlaybackSessionOptions,
+} from './types';
+
+interface NativeMeshStreamP2P {
+  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,147 @@
+import { DeviceEventEmitter, type EmitterSubscription } from 'react-native';
+
+import { requireNativeModule } from './NativeMeshStreamP2P';
+import type {
+  MeshStreamConfig,
+  MeshStreamDiagnostics,
+  MeshStreamEvent,
+  MeshStreamEventName,
+  MeshStreamSessionInfo,
+  MeshStreamStats,
+  MeshStreamStatus,
+  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 closed = false;
+  private closing?: Promise<void>;
+
+  constructor(info: MeshStreamSessionInfo) {
+    this.clientId = info.clientId;
+    this.sessionId = info.sessionId;
+    this.playbackUrl = info.playbackUrl;
+    this.playbackMode = info.playbackMode;
+    this.fallbackReason = info.fallbackReason;
+  }
+
+  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.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) 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 () => new MeshStreamPlaybackSession(
+      await requireNativeModule().createPlaybackSession(this.clientId, options),
+    ));
+  }
+
+  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 = {
+  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,118 @@
+export type MeshStreamMimeType = 'm3u8' | 'mpd' | 'mp4' | 'mp3';
+
+/** A client can own multiple independent playback sessions. */
+export interface MeshStreamConfig {
+  key: string;
+  p2pEnabled?: boolean;
+}
+
+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/tests/ios/MeshStreamP2PValidationTests.m

@@ -0,0 +1,30 @@
+#import <XCTest/XCTest.h>
+
+#import "../../ios/MeshStreamP2PValidation.h"
+
+@interface MeshStreamP2PValidationTests : XCTestCase
+@end
+
+@implementation MeshStreamP2PValidationTests
+
+- (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