@capgo/capacitor-network-diagnostics 8.0.1

package/dist/esm/definitions.d.ts

@@ -0,0 +1,276 @@
+export type ConnectionType = 'none' | 'wifi' | 'cellular' | 'ethernet' | 'vpn' | 'other' | 'unknown';
+export type UrlTestMethod = 'HEAD' | 'GET';
+export type PacketLossMode = 'tcp' | 'http';
+/**
+ * Current native network state.
+ */
+export interface NetworkStatusResult {
+    /**
+     * True when the platform reports an active network path.
+     */
+    connected: boolean;
+    /**
+     * Best-effort active transport type.
+     */
+    connectionType: ConnectionType;
+    /**
+     * True when the OS marks the network as internet-capable or validated.
+     */
+    internetReachable: boolean;
+    /**
+     * True for metered or expensive network paths.
+     */
+    expensive?: boolean;
+    /**
+     * True when the OS reports a low-data or constrained network path.
+     */
+    constrained?: boolean;
+    /**
+     * True when Android reports captive portal capability.
+     */
+    captivePortal?: boolean;
+    /**
+     * Native platform details useful for debugging.
+     */
+    details?: Record<string, string | number | boolean>;
+}
+/**
+ * Options for native HTTP URL reachability checks.
+ */
+export interface UrlTestOptions {
+    /**
+     * HTTP or HTTPS URL to test.
+     */
+    url: string;
+    /**
+     * HTTP method. Defaults to `HEAD`.
+     */
+    method?: UrlTestMethod;
+    /**
+     * Request timeout in milliseconds. Defaults to `10000`.
+     */
+    timeoutMs?: number;
+    /**
+     * Follow redirects. Defaults to `true`.
+     */
+    followRedirects?: boolean;
+}
+/**
+ * Native HTTP URL reachability result.
+ */
+export interface UrlTestResult {
+    url: string;
+    method: UrlTestMethod;
+    ok: boolean;
+    reachable: boolean;
+    durationMs: number;
+    statusCode?: number;
+    finalUrl?: string;
+    errorCode?: string;
+    errorMessage?: string;
+}
+/**
+ * Options for native TCP port checks.
+ */
+export interface PortTestOptions {
+    /**
+     * Hostname or IP address.
+     */
+    host: string;
+    /**
+     * TCP port to open.
+     */
+    port: number;
+    /**
+     * Socket timeout in milliseconds. Defaults to `5000`.
+     */
+    timeoutMs?: number;
+}
+/**
+ * Native TCP port check result.
+ */
+export interface PortTestResult {
+    host: string;
+    port: number;
+    open: boolean;
+    durationMs: number;
+    errorCode?: string;
+    errorMessage?: string;
+}
+/**
+ * Options for native WebSocket handshake checks.
+ */
+export interface WebSocketTestOptions {
+    /**
+     * `ws://` or `wss://` URL to test.
+     */
+    url: string;
+    /**
+     * Handshake timeout in milliseconds. Defaults to `10000`.
+     */
+    timeoutMs?: number;
+}
+/**
+ * Native WebSocket handshake result.
+ */
+export interface WebSocketTestResult {
+    url: string;
+    open: boolean;
+    durationMs: number;
+    protocol?: string;
+    statusCode?: number;
+    errorCode?: string;
+    errorMessage?: string;
+}
+/**
+ * Options for native download speed measurement.
+ */
+export interface DownloadSpeedTestOptions {
+    /**
+     * HTTP or HTTPS URL returning a downloadable body.
+     */
+    url: string;
+    /**
+     * Maximum bytes to read before stopping. Defaults to `5242880` (5 MiB).
+     */
+    maxBytes?: number;
+    /**
+     * Request timeout in milliseconds. Defaults to `30000`.
+     */
+    timeoutMs?: number;
+}
+/**
+ * Native download speed measurement result.
+ */
+export interface DownloadSpeedTestResult {
+    url: string;
+    ok: boolean;
+    durationMs: number;
+    bytesDownloaded: number;
+    bytesPerSecond: number;
+    mbps: number;
+    statusCode?: number;
+    errorCode?: string;
+    errorMessage?: string;
+}
+/**
+ * Options for packet loss measurement.
+ *
+ * Native apps cannot rely on raw ICMP ping on both iOS and Android, so this
+ * method measures application-level loss with repeated TCP connects or HTTP
+ * requests.
+ */
+export interface PacketLossTestOptions {
+    /**
+     * Probe mode. Defaults to `tcp` when host/port is provided, otherwise `http`.
+     */
+    mode?: PacketLossMode;
+    /**
+     * Hostname or IP address for TCP probes.
+     */
+    host?: string;
+    /**
+     * TCP port for TCP probes.
+     */
+    port?: number;
+    /**
+     * HTTP or HTTPS URL for HTTP probes.
+     */
+    url?: string;
+    /**
+     * Number of probes to send. Defaults to `10`.
+     */
+    count?: number;
+    /**
+     * Per-probe timeout in milliseconds. Defaults to `3000`.
+     */
+    timeoutMs?: number;
+    /**
+     * Delay between probes in milliseconds. Defaults to `250`.
+     */
+    intervalMs?: number;
+}
+/**
+ * Application-level packet loss result.
+ */
+export interface PacketLossTestResult {
+    mode: PacketLossMode;
+    target: string;
+    sent: number;
+    received: number;
+    lost: number;
+    lossPercent: number;
+    averageLatencyMs?: number;
+    minLatencyMs?: number;
+    maxLatencyMs?: number;
+    errorCode?: string;
+    errorMessage?: string;
+}
+/**
+ * Options for a combined native network diagnostic run.
+ */
+export interface RunDiagnosticsOptions {
+    urls?: UrlTestOptions[];
+    ports?: PortTestOptions[];
+    websockets?: WebSocketTestOptions[];
+    download?: DownloadSpeedTestOptions;
+    packetLoss?: PacketLossTestOptions;
+}
+/**
+ * Combined native network diagnostic result.
+ */
+export interface RunDiagnosticsResult {
+    status: NetworkStatusResult;
+    urls: UrlTestResult[];
+    ports: PortTestResult[];
+    websockets: WebSocketTestResult[];
+    issues: string[];
+    download?: DownloadSpeedTestResult;
+    packetLoss?: PacketLossTestResult;
+}
+/**
+ * Plugin version payload.
+ */
+export interface PluginVersionResult {
+    /**
+     * Version identifier returned by the platform implementation.
+     */
+    version: string;
+}
+/**
+ * Native network diagnostics API.
+ */
+export interface NetworkDiagnosticsPlugin {
+    /**
+     * Read the current native connection type and platform network flags.
+     */
+    getNetworkStatus(): Promise<NetworkStatusResult>;
+    /**
+     * Test whether an HTTP or HTTPS URL can be reached from native networking.
+     */
+    testUrl(options: UrlTestOptions): Promise<UrlTestResult>;
+    /**
+     * Test whether a TCP host:port can be opened from native networking.
+     */
+    testPort(options: PortTestOptions): Promise<PortTestResult>;
+    /**
+     * Test whether a WebSocket URL can complete its native handshake.
+     */
+    testWebSocket(options: WebSocketTestOptions): Promise<WebSocketTestResult>;
+    /**
+     * Measure download throughput from a native HTTP request.
+     */
+    testDownloadSpeed(options: DownloadSpeedTestOptions): Promise<DownloadSpeedTestResult>;
+    /**
+     * Estimate application-level packet loss with repeated TCP or HTTP probes.
+     */
+    testPacketLoss(options: PacketLossTestOptions): Promise<PacketLossTestResult>;
+    /**
+     * Run several diagnostics and return a compact issue list.
+     */
+    runDiagnostics(options?: RunDiagnosticsOptions): Promise<RunDiagnosticsResult>;
+    /**
+     * Returns the platform implementation version marker.
+     */
+    getPluginVersion(): Promise<PluginVersionResult>;
+}

package/dist/esm/definitions.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=definitions.js.map

package/dist/esm/definitions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"definitions.js","sourceRoot":"","sources":["../../src/definitions.ts"],"names":[],"mappings":"","sourcesContent":["export type ConnectionType = 'none' | 'wifi' | 'cellular' | 'ethernet' | 'vpn' | 'other' | 'unknown';\n\nexport type UrlTestMethod = 'HEAD' | 'GET';\n\nexport type PacketLossMode = 'tcp' | 'http';\n\n/**\n * Current native network state.\n */\nexport interface NetworkStatusResult {\n  /**\n   * True when the platform reports an active network path.\n   */\n  connected: boolean;\n\n  /**\n   * Best-effort active transport type.\n   */\n  connectionType: ConnectionType;\n\n  /**\n   * True when the OS marks the network as internet-capable or validated.\n   */\n  internetReachable: boolean;\n\n  /**\n   * True for metered or expensive network paths.\n   */\n  expensive?: boolean;\n\n  /**\n   * True when the OS reports a low-data or constrained network path.\n   */\n  constrained?: boolean;\n\n  /**\n   * True when Android reports captive portal capability.\n   */\n  captivePortal?: boolean;\n\n  /**\n   * Native platform details useful for debugging.\n   */\n  details?: Record<string, string | number | boolean>;\n}\n\n/**\n * Options for native HTTP URL reachability checks.\n */\nexport interface UrlTestOptions {\n  /**\n   * HTTP or HTTPS URL to test.\n   */\n  url: string;\n\n  /**\n   * HTTP method. Defaults to `HEAD`.\n   */\n  method?: UrlTestMethod;\n\n  /**\n   * Request timeout in milliseconds. Defaults to `10000`.\n   */\n  timeoutMs?: number;\n\n  /**\n   * Follow redirects. Defaults to `true`.\n   */\n  followRedirects?: boolean;\n}\n\n/**\n * Native HTTP URL reachability result.\n */\nexport interface UrlTestResult {\n  url: string;\n  method: UrlTestMethod;\n  ok: boolean;\n  reachable: boolean;\n  durationMs: number;\n  statusCode?: number;\n  finalUrl?: string;\n  errorCode?: string;\n  errorMessage?: string;\n}\n\n/**\n * Options for native TCP port checks.\n */\nexport interface PortTestOptions {\n  /**\n   * Hostname or IP address.\n   */\n  host: string;\n\n  /**\n   * TCP port to open.\n   */\n  port: number;\n\n  /**\n   * Socket timeout in milliseconds. Defaults to `5000`.\n   */\n  timeoutMs?: number;\n}\n\n/**\n * Native TCP port check result.\n */\nexport interface PortTestResult {\n  host: string;\n  port: number;\n  open: boolean;\n  durationMs: number;\n  errorCode?: string;\n  errorMessage?: string;\n}\n\n/**\n * Options for native WebSocket handshake checks.\n */\nexport interface WebSocketTestOptions {\n  /**\n   * `ws://` or `wss://` URL to test.\n   */\n  url: string;\n\n  /**\n   * Handshake timeout in milliseconds. Defaults to `10000`.\n   */\n  timeoutMs?: number;\n}\n\n/**\n * Native WebSocket handshake result.\n */\nexport interface WebSocketTestResult {\n  url: string;\n  open: boolean;\n  durationMs: number;\n  protocol?: string;\n  statusCode?: number;\n  errorCode?: string;\n  errorMessage?: string;\n}\n\n/**\n * Options for native download speed measurement.\n */\nexport interface DownloadSpeedTestOptions {\n  /**\n   * HTTP or HTTPS URL returning a downloadable body.\n   */\n  url: string;\n\n  /**\n   * Maximum bytes to read before stopping. Defaults to `5242880` (5 MiB).\n   */\n  maxBytes?: number;\n\n  /**\n   * Request timeout in milliseconds. Defaults to `30000`.\n   */\n  timeoutMs?: number;\n}\n\n/**\n * Native download speed measurement result.\n */\nexport interface DownloadSpeedTestResult {\n  url: string;\n  ok: boolean;\n  durationMs: number;\n  bytesDownloaded: number;\n  bytesPerSecond: number;\n  mbps: number;\n  statusCode?: number;\n  errorCode?: string;\n  errorMessage?: string;\n}\n\n/**\n * Options for packet loss measurement.\n *\n * Native apps cannot rely on raw ICMP ping on both iOS and Android, so this\n * method measures application-level loss with repeated TCP connects or HTTP\n * requests.\n */\nexport interface PacketLossTestOptions {\n  /**\n   * Probe mode. Defaults to `tcp` when host/port is provided, otherwise `http`.\n   */\n  mode?: PacketLossMode;\n\n  /**\n   * Hostname or IP address for TCP probes.\n   */\n  host?: string;\n\n  /**\n   * TCP port for TCP probes.\n   */\n  port?: number;\n\n  /**\n   * HTTP or HTTPS URL for HTTP probes.\n   */\n  url?: string;\n\n  /**\n   * Number of probes to send. Defaults to `10`.\n   */\n  count?: number;\n\n  /**\n   * Per-probe timeout in milliseconds. Defaults to `3000`.\n   */\n  timeoutMs?: number;\n\n  /**\n   * Delay between probes in milliseconds. Defaults to `250`.\n   */\n  intervalMs?: number;\n}\n\n/**\n * Application-level packet loss result.\n */\nexport interface PacketLossTestResult {\n  mode: PacketLossMode;\n  target: string;\n  sent: number;\n  received: number;\n  lost: number;\n  lossPercent: number;\n  averageLatencyMs?: number;\n  minLatencyMs?: number;\n  maxLatencyMs?: number;\n  errorCode?: string;\n  errorMessage?: string;\n}\n\n/**\n * Options for a combined native network diagnostic run.\n */\nexport interface RunDiagnosticsOptions {\n  urls?: UrlTestOptions[];\n  ports?: PortTestOptions[];\n  websockets?: WebSocketTestOptions[];\n  download?: DownloadSpeedTestOptions;\n  packetLoss?: PacketLossTestOptions;\n}\n\n/**\n * Combined native network diagnostic result.\n */\nexport interface RunDiagnosticsResult {\n  status: NetworkStatusResult;\n  urls: UrlTestResult[];\n  ports: PortTestResult[];\n  websockets: WebSocketTestResult[];\n  issues: string[];\n  download?: DownloadSpeedTestResult;\n  packetLoss?: PacketLossTestResult;\n}\n\n/**\n * Plugin version payload.\n */\nexport interface PluginVersionResult {\n  /**\n   * Version identifier returned by the platform implementation.\n   */\n  version: string;\n}\n\n/**\n * Native network diagnostics API.\n */\nexport interface NetworkDiagnosticsPlugin {\n  /**\n   * Read the current native connection type and platform network flags.\n   */\n  getNetworkStatus(): Promise<NetworkStatusResult>;\n\n  /**\n   * Test whether an HTTP or HTTPS URL can be reached from native networking.\n   */\n  testUrl(options: UrlTestOptions): Promise<UrlTestResult>;\n\n  /**\n   * Test whether a TCP host:port can be opened from native networking.\n   */\n  testPort(options: PortTestOptions): Promise<PortTestResult>;\n\n  /**\n   * Test whether a WebSocket URL can complete its native handshake.\n   */\n  testWebSocket(options: WebSocketTestOptions): Promise<WebSocketTestResult>;\n\n  /**\n   * Measure download throughput from a native HTTP request.\n   */\n  testDownloadSpeed(options: DownloadSpeedTestOptions): Promise<DownloadSpeedTestResult>;\n\n  /**\n   * Estimate application-level packet loss with repeated TCP or HTTP probes.\n   */\n  testPacketLoss(options: PacketLossTestOptions): Promise<PacketLossTestResult>;\n\n  /**\n   * Run several diagnostics and return a compact issue list.\n   */\n  runDiagnostics(options?: RunDiagnosticsOptions): Promise<RunDiagnosticsResult>;\n\n  /**\n   * Returns the platform implementation version marker.\n   */\n  getPluginVersion(): Promise<PluginVersionResult>;\n}\n"]}

package/dist/esm/index.d.ts

@@ -0,0 +1,4 @@
+import type { NetworkDiagnosticsPlugin } from './definitions';
+declare const NetworkDiagnostics: NetworkDiagnosticsPlugin;
+export * from './definitions';
+export { NetworkDiagnostics };

package/dist/esm/index.js

@@ -0,0 +1,7 @@
+import { registerPlugin } from '@capacitor/core';
+const NetworkDiagnostics = registerPlugin('NetworkDiagnostics', {
+    web: () => import('./web').then((m) => new m.NetworkDiagnosticsWeb()),
+});
+export * from './definitions';
+export { NetworkDiagnostics };
+//# sourceMappingURL=index.js.map

package/dist/esm/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAIjD,MAAM,kBAAkB,GAAG,cAAc,CAA2B,oBAAoB,EAAE;IACxF,GAAG,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC,qBAAqB,EAAE,CAAC;CACtE,CAAC,CAAC;AAEH,cAAc,eAAe,CAAC;AAC9B,OAAO,EAAE,kBAAkB,EAAE,CAAC","sourcesContent":["import { registerPlugin } from '@capacitor/core';\n\nimport type { NetworkDiagnosticsPlugin } from './definitions';\n\nconst NetworkDiagnostics = registerPlugin<NetworkDiagnosticsPlugin>('NetworkDiagnostics', {\n  web: () => import('./web').then((m) => new m.NetworkDiagnosticsWeb()),\n});\n\nexport * from './definitions';\nexport { NetworkDiagnostics };\n"]}

package/dist/esm/web.d.ts

@@ -0,0 +1,24 @@
+import { WebPlugin } from '@capacitor/core';
+import type { DownloadSpeedTestOptions, DownloadSpeedTestResult, NetworkDiagnosticsPlugin, NetworkStatusResult, PacketLossTestOptions, PacketLossTestResult, PluginVersionResult, PortTestOptions, PortTestResult, RunDiagnosticsOptions, RunDiagnosticsResult, UrlTestOptions, UrlTestResult, WebSocketTestOptions, WebSocketTestResult } from './definitions';
+export declare class NetworkDiagnosticsWeb extends WebPlugin implements NetworkDiagnosticsPlugin {
+    getNetworkStatus(): Promise<NetworkStatusResult>;
+    testUrl(options: UrlTestOptions): Promise<UrlTestResult>;
+    testPort(options: PortTestOptions): Promise<PortTestResult>;
+    testWebSocket(options: WebSocketTestOptions): Promise<WebSocketTestResult>;
+    testDownloadSpeed(options: DownloadSpeedTestOptions): Promise<DownloadSpeedTestResult>;
+    testPacketLoss(options: PacketLossTestOptions): Promise<PacketLossTestResult>;
+    runDiagnostics(options?: RunDiagnosticsOptions): Promise<RunDiagnosticsResult>;
+    getPluginVersion(): Promise<PluginVersionResult>;
+    private buildIssues;
+    private elapsed;
+    private errorCode;
+    private errorMessage;
+    private mapConnectionType;
+    private normalizeMethod;
+    private packetLossMode;
+    private packetLossResult;
+    private packetLossTarget;
+    private positiveNumber;
+    private sleep;
+    private timeout;
+}