@networkdiagnostics/sdk 0.1.0-pre.1

package/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+All notable changes to `@networkdiagnostics/sdk` are documented here.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/);
+this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- Initial scaffolding: package skeleton, TypeScript build via tsup, vitest test runner.
+- `NetworkTests` class with `runUdpTest()` and `runDnsLeakTest()` methods.
+- UDP throughput probe: WebSocket signaling, RTCPeerConnection + DataChannel orchestration,
+  client-side ack loop, server-authoritative result delivery via `test-complete` message.
+- DNS leak probe: parallel FQDN trigger via `Image()` (primary) and `fetch(no-cors)` (fallback).
+- React adapters: `useUdpTest`, `useDnsLeakTest` hooks under `@networkdiagnostics/sdk/react`.
+- Error hierarchy: `NetworkTestsError`, `AbortError`, `TimeoutError`.
+- Unit tests for signaling type guard, error classes, and DNS trigger.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 networktests.com
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,178 @@
+# @networkdiagnostics/sdk
+
+Browser SDK for the [networktests.com API](https://api.networktests.com/v1/docs). Run UDP throughput tests and DNS-leak probes from your frontend without reimplementing WebRTC signaling or DNS query orchestration.
+
+```
+npm install @networkdiagnostics/sdk
+```
+
+## Why an SDK?
+
+Two of the endpoints on `api.networktests.com/v1/*` need cooperation from the end-user's browser:
+
+- **UDP throughput** requires a WebRTC DataChannel — the browser pushes thousands of packets through it so we can measure loss, latency, and jitter from the path your customer's network actually uses.
+- **DNS leak** requires the browser to resolve 10 short-lived FQDNs so our authoritative DNS server can record which recursive resolver each query hit.
+
+The SDK hides this. Your application code stays a few lines.
+
+## Security model
+
+**The SDK never sees your API key.**
+
+```
+┌──────────────────────────────┐         ┌────────────────────────────┐
+│   Your backend               │  HTTPS  │  api.networktests.com      │
+│   (holds the API key)        │  ────▶  │  POST /v1/probe/udp/       │
+│                              │  ◀────  │       sessions             │
+│   POST /v1/probe/udp/        │         │  → { sessionId, wsUrl }    │
+│        sessions              │         └────────────────────────────┘
+└──────┬───────────────────────┘
+       │ session (opaque ticket)
+       ▼
+┌──────────────────────────────┐         ┌────────────────────────────┐
+│   Your frontend              │   WSS   │  api.networktests.com      │
+│   (this SDK)                 │  ────▶  │  /ws/v1/probe/udp/<id>     │
+│   nt.runUdpTest(session)     │         └────────────────────────────┘
+└──────────────────────────────┘
+```
+
+Your backend mints a single-use session ticket via the authenticated API and ships it to the browser. The SDK uses the ticket to talk to our signaling server. Same shape as Stripe Elements, Twilio, or 100ms — frontend SDKs never hold long-lived secrets.
+
+## Quickstart — UDP throughput
+
+**Backend** (any language, here in Node):
+
+```js
+const r = await fetch("https://api.networktests.com/v1/probe/udp/sessions", {
+  method: "POST",
+  headers: {
+    "Authorization": "Bearer ntsk_live_…",
+    "Content-Type": "application/json",
+  },
+  body: JSON.stringify({ duration: 10, rate: 200, packetSize: 256 }),
+});
+const { data } = await r.json();
+// → { sessionId, wsUrl, iceServers, duration, rate, packetSize }
+res.json(data);
+```
+
+**Frontend**:
+
+```ts
+import { NetworkTests } from "@networkdiagnostics/sdk";
+
+const nt = new NetworkTests();
+const session = await fetch("/my-backend/start-udp").then(r => r.json());
+
+const result = await nt.runUdpTest(session, {
+  onProgress: ({ packetsSent, packetsReceived, lossPercent }) => {
+    console.log(`${packetsReceived}/${packetsSent} (${lossPercent}%)`);
+  },
+});
+
+console.log(`loss: ${result.lossPercent}%`);
+console.log(`p95 latency: ${result.latency.p95} ms`);
+console.log(`jitter: ${result.jitter} ms`);
+```
+
+## Quickstart — DNS leak
+
+**Backend**:
+
+```js
+const r = await fetch("https://api.networktests.com/v1/probe/dns-leak/sessions", {
+  method: "POST",
+  headers: { "Authorization": "Bearer ntsk_live_…" },
+});
+const { data } = await r.json();
+// → { sessionId, fqdns: [10 short-lived names] }
+res.json(data);
+```
+
+**Frontend**:
+
+```ts
+import { NetworkTests } from "@networkdiagnostics/sdk";
+
+const nt = new NetworkTests();
+const session = await fetch("/my-backend/start-leak-test").then(r => r.json());
+await nt.runDnsLeakTest(session);
+
+// Poll your backend for the resolver list.
+const leak = await fetch(`/my-backend/leak-results/${session.sessionId}`)
+  .then(r => r.json());
+// → { resolvers: [{ ip, org, asn, country, encrypted, known_provider }, ...] }
+```
+
+## React
+
+```tsx
+import { useUdpTest } from "@networkdiagnostics/sdk/react";
+
+function SpeedTest({ session }) {
+  const { run, isRunning, progress, result, error } = useUdpTest();
+
+  if (error) return <div>Error: {error.message}</div>;
+  if (result) return <div>Loss: {result.lossPercent}%</div>;
+  if (isRunning) return <div>{progress?.packetsReceived ?? 0} packets…</div>;
+  return <button onClick={() => run(session)}>Start</button>;
+}
+```
+
+## CDN drop-in (no build step)
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/@networkdiagnostics/sdk@0/dist/networktests.umd.js"></script>
+<script>
+  const nt = new NetworkTests.NetworkTests();
+  // ...
+</script>
+```
+
+## API reference
+
+### `new NetworkTests()`
+
+Takes no arguments. The SDK is keyless on the wire.
+
+### `nt.runUdpTest(session, options?)`
+
+| Param | Type | Notes |
+|---|---|---|
+| `session` | `UdpSession` | From your backend's call to `POST /v1/probe/udp/sessions`. |
+| `options.onProgress` | `(p: UdpProgress) => void` | Fired ~10× per second during the test. |
+| `options.signal` | `AbortSignal` | Cancels the test cleanly. |
+| `options.timeoutMs` | `number` | Hard timeout. Defaults to `(session.duration + 10) * 1000`. |
+
+Resolves with `UdpResult`. Rejects with `NetworkTestsError`, `AbortError`, or `TimeoutError`.
+
+### `nt.runDnsLeakTest(session, options?)`
+
+| Param | Type | Notes |
+|---|---|---|
+| `session` | `DnsLeakSession` | From `POST /v1/probe/dns-leak/sessions`. |
+| `options.onResolved` | `(fqdn: string) => void` | Fired per FQDN. |
+| `options.signal` | `AbortSignal` | Cancels in-flight triggers. |
+| `options.timeoutMs` | `number` | Default 15000. |
+
+Resolves with `void` once all triggers complete. The resolver list lives server-side — poll the `GET /v1/probe/dns-leak/sessions/:id` endpoint from your backend.
+
+### Errors
+
+```ts
+import {
+  NetworkTestsError,   // base class with .code
+  AbortError,          // signal fired
+  TimeoutError,        // exceeded timeoutMs
+} from "@networkdiagnostics/sdk";
+```
+
+Common `code` values: `WS_ERROR`, `WS_CLOSED`, `DC_ERROR`, `DC_CLOSED`, `SERVER_ERROR`, `TEST_STOPPED`, `BAD_STATE`, `UNKNOWN`.
+
+## Browser support
+
+Evergreen Chromium, Firefox, Safari, and Edge from 2022 onward. Requires `RTCPeerConnection`, `RTCDataChannel`, `WebSocket`, and either `Image` or `fetch` with `mode: "no-cors"`. No Node, no React Native in v0.1.
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,415 @@
+'use strict';
+
+// src/errors.ts
+var NetworkTestsError = class extends Error {
+  constructor(code, message) {
+    super(message);
+    this.name = "NetworkTestsError";
+    this.code = code;
+  }
+};
+var AbortError = class extends NetworkTestsError {
+  constructor(message = "Operation aborted") {
+    super("ABORTED", message);
+    this.name = "AbortError";
+  }
+};
+var TimeoutError = class extends NetworkTestsError {
+  constructor(message = "Operation timed out") {
+    super("TIMEOUT", message);
+    this.name = "TimeoutError";
+  }
+};
+
+// src/udp/webrtc.ts
+function createPeerConnection(iceServers) {
+  return new RTCPeerConnection({ iceServers });
+}
+function setupDataChannel(pc) {
+  const channel = pc.createDataChannel("test", { ordered: false });
+  const ready = new Promise((resolve, reject) => {
+    const onOpen = () => {
+      cleanup();
+      resolve();
+    };
+    const onError = () => {
+      cleanup();
+      reject(new NetworkTestsError("DC_ERROR", "DataChannel error before open"));
+    };
+    const onClose = () => {
+      cleanup();
+      reject(new NetworkTestsError("DC_CLOSED", "DataChannel closed before open"));
+    };
+    function cleanup() {
+      channel.removeEventListener("open", onOpen);
+      channel.removeEventListener("error", onError);
+      channel.removeEventListener("close", onClose);
+    }
+    channel.addEventListener("open", onOpen);
+    channel.addEventListener("error", onError);
+    channel.addEventListener("close", onClose);
+  });
+  return { channel, ready };
+}
+async function createOffer(pc) {
+  const offer = await pc.createOffer();
+  await pc.setLocalDescription(offer);
+  return offer;
+}
+async function applyAnswer(pc, sdp) {
+  await pc.setRemoteDescription({ type: "answer", sdp });
+}
+
+// src/udp/packetLoop.ts
+function startPacketLoop(opts) {
+  const { channel, onProgress } = opts;
+  const progressMs = opts.progressIntervalMs ?? 100;
+  const startTs = Date.now();
+  let received = 0;
+  let highestSeq = -1;
+  let stopped = false;
+  const onMsg = (ev) => {
+    if (stopped) return;
+    try {
+      const msg = JSON.parse(ev.data);
+      if (msg && msg.type === "packet" && typeof msg.seq === "number") {
+        received++;
+        if (msg.seq > highestSeq) highestSeq = msg.seq;
+        try {
+          channel.send(JSON.stringify({ type: "ack", seq: msg.seq }));
+        } catch {
+        }
+      }
+    } catch {
+    }
+  };
+  channel.addEventListener("message", onMsg);
+  let progressTimer = null;
+  if (onProgress) {
+    progressTimer = setInterval(() => {
+      if (stopped) return;
+      const sent = highestSeq + 1;
+      const loss = sent > 0 ? (sent - received) / sent * 100 : 0;
+      onProgress({
+        packetsSent: sent,
+        packetsReceived: received,
+        lossPercent: Math.round(loss * 100) / 100,
+        elapsedMs: Date.now() - startTs
+      });
+    }, progressMs);
+  }
+  return {
+    stop() {
+      if (stopped) return;
+      stopped = true;
+      channel.removeEventListener("message", onMsg);
+      if (progressTimer) clearInterval(progressTimer);
+    }
+  };
+}
+
+// src/udp/signaling.ts
+function isServerMsg(value) {
+  return typeof value === "object" && value !== null && typeof value.type === "string";
+}
+
+// src/udp/index.ts
+var DEFAULT_ICE_SERVERS = [
+  { urls: "stun:stun.l.google.com:19302" }
+];
+async function runUdpTest(session, options = {}) {
+  const startedAt = Date.now();
+  const { signal, onProgress } = options;
+  const timeoutMs = options.timeoutMs ?? ((session.duration ?? 30) + 10) * 1e3;
+  if (signal?.aborted) throw new AbortError();
+  const ws = new WebSocket(session.wsUrl);
+  ws.binaryType = "arraybuffer";
+  let pc = null;
+  let dataChannel = null;
+  let packetLoop = null;
+  let timeoutHandle = null;
+  let abortHandler = null;
+  const cleanup = () => {
+    if (timeoutHandle) clearTimeout(timeoutHandle);
+    if (abortHandler && signal) signal.removeEventListener("abort", abortHandler);
+    packetLoop?.stop();
+    try {
+      dataChannel?.close();
+    } catch {
+    }
+    try {
+      pc?.close();
+    } catch {
+    }
+    if (ws.readyState === WebSocket.OPEN || ws.readyState === WebSocket.CONNECTING) {
+      try {
+        ws.close();
+      } catch {
+      }
+    }
+  };
+  return new Promise((resolve, reject) => {
+    const fail = (err) => {
+      cleanup();
+      reject(err);
+    };
+    const succeed = (result) => {
+      cleanup();
+      resolve(result);
+    };
+    timeoutHandle = setTimeout(
+      () => fail(new TimeoutError(`UDP test exceeded ${timeoutMs}ms`)),
+      timeoutMs
+    );
+    if (signal) {
+      abortHandler = () => fail(new AbortError());
+      signal.addEventListener("abort", abortHandler, { once: true });
+    }
+    const send = (msg) => {
+      if (ws.readyState === WebSocket.OPEN) ws.send(JSON.stringify(msg));
+    };
+    ws.addEventListener(
+      "error",
+      () => fail(new NetworkTestsError("WS_ERROR", "WebSocket error"))
+    );
+    ws.addEventListener("close", (ev) => {
+      if (ws.readyState === WebSocket.CLOSED) {
+        const reason = ev.reason || `WebSocket closed (code ${ev.code})`;
+        fail(new NetworkTestsError("WS_CLOSED", reason));
+      }
+    });
+    ws.addEventListener("open", async () => {
+    });
+    ws.addEventListener("message", async (ev) => {
+      let msg;
+      try {
+        msg = JSON.parse(String(ev.data));
+      } catch {
+        return;
+      }
+      if (!isServerMsg(msg)) return;
+      const m = msg;
+      try {
+        switch (m.type) {
+          case "welcome": {
+            const iceServers = [
+              ...session.iceServers ?? DEFAULT_ICE_SERVERS
+            ];
+            if (m.turn) {
+              iceServers.push({
+                urls: m.turn.urls,
+                username: m.turn.username,
+                credential: m.turn.credential
+              });
+            }
+            pc = createPeerConnection(iceServers);
+            pc.addEventListener("icecandidate", (e) => {
+              if (e.candidate) {
+                send({ type: "ice-candidate", candidate: e.candidate.toJSON() });
+              }
+            });
+            const dcSetup = setupDataChannel(pc);
+            dataChannel = dcSetup.channel;
+            const offer = await createOffer(pc);
+            send({ type: "offer", sdp: offer.sdp ?? "" });
+            dcSetup.ready.then(() => send({ type: "datachannel-ready" })).catch((err) => fail(toError(err)));
+            break;
+          }
+          case "answer": {
+            if (!pc) throw new NetworkTestsError("BAD_STATE", "answer before welcome");
+            await applyAnswer(pc, m.sdp.sdp);
+            break;
+          }
+          case "ice-candidate": {
+            if (!pc) return;
+            try {
+              await pc.addIceCandidate(m.candidate);
+            } catch {
+            }
+            break;
+          }
+          case "datachannel-open": {
+            if (!dataChannel) throw new NetworkTestsError("BAD_STATE", "no DC");
+            packetLoop = startPacketLoop({ channel: dataChannel, onProgress });
+            send({
+              type: "start-packet-test",
+              duration: session.duration,
+              rate: session.rate,
+              packetSize: session.packetSize
+            });
+            break;
+          }
+          case "test-started":
+            break;
+          case "test-complete": {
+            const r = m.results;
+            succeed({
+              sessionId: session.sessionId,
+              packetsSent: r.packetsSent,
+              packetsReceived: r.packetsReceived,
+              packetsLost: r.packetsLost,
+              lossPercent: r.lossPercent,
+              jitter: r.jitter,
+              latency: {
+                avg: r.latency.avg,
+                min: r.latency.min,
+                max: r.latency.max,
+                p50: r.latency.p50,
+                p95: r.latency.p95,
+                samples: r.latency.samples
+              },
+              durationMs: Date.now() - startedAt,
+              completedAt: (/* @__PURE__ */ new Date()).toISOString()
+            });
+            break;
+          }
+          case "test-stopped":
+            fail(new NetworkTestsError("TEST_STOPPED", "Server stopped the test"));
+            break;
+          case "error":
+            fail(new NetworkTestsError("SERVER_ERROR", m.message));
+            break;
+        }
+      } catch (err) {
+        fail(toError(err));
+      }
+    });
+  });
+}
+function toError(value) {
+  if (value instanceof Error) return value;
+  return new NetworkTestsError("UNKNOWN", String(value));
+}
+
+// src/dnsleak/trigger.ts
+var ABORT_AFTER_MS = 5e3;
+function triggerDnsResolution(fqdn, signal) {
+  if (signal?.aborted) return Promise.resolve();
+  if (typeof Image !== "undefined") {
+    return triggerViaImage(fqdn, signal);
+  }
+  return triggerViaFetch(fqdn, signal);
+}
+function triggerViaImage(fqdn, signal) {
+  return new Promise((resolve) => {
+    const img = new Image();
+    let settled = false;
+    const finish = () => {
+      if (settled) return;
+      settled = true;
+      img.src = "";
+      resolve();
+    };
+    const onAbort = () => finish();
+    signal?.addEventListener("abort", onAbort, { once: true });
+    const timer = setTimeout(finish, ABORT_AFTER_MS);
+    img.onload = () => {
+      clearTimeout(timer);
+      finish();
+    };
+    img.onerror = () => {
+      clearTimeout(timer);
+      finish();
+    };
+    img.src = `https://${fqdn}/_/leak.gif?t=${Date.now()}-${Math.random().toString(36).slice(2)}`;
+  });
+}
+function triggerViaFetch(fqdn, signal) {
+  const controller = new AbortController();
+  const abortSignal = signal ? mergeSignals(signal, controller.signal) : controller.signal;
+  const timer = setTimeout(() => controller.abort(), ABORT_AFTER_MS);
+  return fetch(`https://${fqdn}/_/leak?t=${Date.now()}`, {
+    method: "GET",
+    mode: "no-cors",
+    cache: "no-store",
+    signal: abortSignal
+  }).catch(() => void 0).finally(() => clearTimeout(timer)).then(() => void 0);
+}
+function mergeSignals(a, b) {
+  const c = new AbortController();
+  const onAbort = () => c.abort();
+  if (a.aborted || b.aborted) c.abort();
+  else {
+    a.addEventListener("abort", onAbort, { once: true });
+    b.addEventListener("abort", onAbort, { once: true });
+  }
+  return c.signal;
+}
+
+// src/dnsleak/index.ts
+async function runDnsLeakTest(session, options = {}) {
+  if (options.signal?.aborted) throw new AbortError();
+  const timeoutMs = options.timeoutMs ?? 15e3;
+  let timeoutHandle = null;
+  const timeoutController = new AbortController();
+  const combinedSignal = mergeSignals2(options.signal, timeoutController.signal);
+  const timeoutPromise = new Promise((_, reject) => {
+    timeoutHandle = setTimeout(() => {
+      timeoutController.abort();
+      reject(new TimeoutError(`DNS-leak test exceeded ${timeoutMs}ms`));
+    }, timeoutMs);
+  });
+  const abortPromise = new Promise((_, reject) => {
+    options.signal?.addEventListener(
+      "abort",
+      () => reject(new AbortError()),
+      { once: true }
+    );
+  });
+  const triggers = session.fqdns.map(
+    (fqdn) => triggerDnsResolution(fqdn, combinedSignal).then(() => {
+      options.onResolved?.(fqdn);
+    })
+  );
+  try {
+    await Promise.race([
+      Promise.all(triggers),
+      timeoutPromise,
+      abortPromise
+    ]);
+  } finally {
+    if (timeoutHandle) clearTimeout(timeoutHandle);
+  }
+}
+function mergeSignals2(a, b) {
+  if (!a) return b;
+  const c = new AbortController();
+  if (a.aborted || b.aborted) c.abort();
+  else {
+    a.addEventListener("abort", () => c.abort(), { once: true });
+    b.addEventListener("abort", () => c.abort(), { once: true });
+  }
+  return c.signal;
+}
+
+// src/client.ts
+var NetworkTests = class {
+  /**
+   * Run the UDP throughput probe to completion.
+   *
+   * Opens a WebSocket to `session.wsUrl`, negotiates a WebRTC DataChannel,
+   * runs the packet-loss test, and resolves with the final stats once the
+   * server emits `test-complete`.
+   */
+  runUdpTest(session, options) {
+    return runUdpTest(session, options);
+  }
+  /**
+   * Trigger DNS resolution of every FQDN in the session. Returns once all
+   * triggers have fired (or errored — errors are expected because the
+   * fake server returns 192.0.2.1).
+   *
+   * Actual resolver IPs are observed server-side. Customer's backend
+   * polls `GET /v1/probe/dns-leak/sessions/:id` to retrieve them.
+   */
+  runDnsLeakTest(session, options) {
+    return runDnsLeakTest(session, options);
+  }
+};
+
+exports.AbortError = AbortError;
+exports.NetworkTests = NetworkTests;
+exports.NetworkTestsError = NetworkTestsError;
+exports.TimeoutError = TimeoutError;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map