@camstack/sdk 0.1.36 → 0.1.37

package/dist/system.d.ts

@@ -57,7 +57,10 @@ export type SystemLiveEventListener<TData = unknown> = (event: SystemLiveEvent<T
 type TrpcClient = TRPCClient<BackendAppRouter>;
 type TrpcWsClient = ReturnType<typeof createWSClient>;
 export declare class System {
-    readonly serverUrl: string;
+    /** Active server base URL. Mutable via `switchServerUrl()` so the
+     *  endpoint-race helper can pivot the transport onto a LAN candidate
+     *  after the initial public-URL bootstrap. */
+    private _serverUrl;
     private readonly useWs;
     private readonly baseRetryMs;
     private readonly maxRetryMs;
@@ -73,6 +76,8 @@ export declare class System {
     private _connectionVersion;
     private readonly connectionListeners;
     constructor(config: SystemConfig);
+    /** Active server base URL (no trailing slash). */
+    get serverUrl(): string;
     get connectionVersion(): number;
     /**
      * Subscribe to connection-state transitions. Called with `('connected'
@@ -132,6 +137,47 @@ export declare class System {
      * client) and rebuilds them. No-op for HTTP transport.
      */
     reconnect(): void;
+    /**
+     * Pivot the underlying tRPC transport onto a different base URL.
+     * Used by the endpoint-race flow: the SDK opens against the public
+     * URL the operator provided, calls `localNetwork.getConnectionEndpoints`
+     * to discover LAN candidates, races them, and (when a faster one wins)
+     * calls `switchServerUrl(winner)` to migrate every subsequent query
+     * onto the LAN path without losing auth state.
+     *
+     * Keeps the auth token. Tears down the WS + mirror and rebuilds them
+     * against the new URL — same machinery as `reconnect()` but with a
+     * different target.
+     */
+    switchServerUrl(nextUrl: string): void;
+    /**
+     * Race the candidate base URLs reported by the hub's `local-network`
+     * cap, pick the fastest one that responds, and (if it's different
+     * from the current URL) pivot the transport onto it.
+     *
+     * Flow:
+     *   1. Query `localNetwork.getConnectionEndpoints({ port })` over the
+     *      already-authenticated tRPC channel — the cap is auth-gated,
+     *      so the LAN IPs never leak to anonymous callers.
+     *   2. For each candidate, fire a HEAD on `{baseUrl}/trpc/health`
+     *      with a short timeout (default 1500ms). The first 2xx wins.
+     *   3. If the winner differs from `this.serverUrl`, call
+     *      `switchServerUrl(winner)` and return it. Otherwise return
+     *      the current URL unchanged.
+     *
+     * Bounded — if every candidate times out we keep the current URL.
+     * Idempotent — safe to call on every connect / reconnect / network
+     * change event.
+     */
+    raceConnectionEndpoints(options?: {
+        /** Per-candidate probe timeout. Default 1500ms. */
+        readonly perCandidateTimeoutMs?: number;
+        /** Skip IPv6 candidates. Default `false`. */
+        readonly ipv4Only?: boolean;
+    }): Promise<{
+        winner: string;
+        switched: boolean;
+    }>;
     /** Tear down WS connection + mirror. The instance is unusable afterwards. */
     close(): void;
     private disposeMirror;
@@ -227,4 +273,25 @@ export declare class System {
 }
 /** Create a `System` instance. Convenience factory. */
 export declare function createSystem(config: SystemConfig): System;
+/**
+ * Race a list of candidate base URLs and return the first one that
+ * responds to `GET {baseUrl}/trpc/health` with a 2xx within
+ * `timeoutMs`. Returns `null` if every candidate fails / times out.
+ *
+ * Implementation notes:
+ *   - Uses `fetch` with `AbortController` for per-candidate cutoff so a
+ *     stalled candidate doesn't pin the wallclock for the whole race.
+ *   - Cancels every still-pending probe as soon as the first one
+ *     succeeds — no wasted bandwidth on the loser candidates.
+ *   - `/trpc/health` is the only endpoint guaranteed to respond on every
+ *     CamStack deployment (registered alongside the tRPC plugin). It is
+ *     intentionally NOT auth-gated since it's used by load balancers /
+ *     uptime probes — same surface every reverse proxy already monitors.
+ *   - HEAD would be nicer but Cloudflare Tunnel + some browsers
+ *     mishandle HEAD on the ingress path; GET is safer.
+ *
+ * Exported so non-System callers (CLI helpers, tests) can race their
+ * own candidate lists without instantiating a full System.
+ */
+export declare function raceFastestEndpoint(candidates: ReadonlyArray<string>, timeoutMs: number): Promise<string | null>;
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camstack/sdk",
-  "version": "0.1.36",
+  "version": "0.1.37",
   "type": "module",
   "main": "dist/index.cjs",
   "module": "dist/index.js",
@@ -16,7 +16,7 @@
     "dist"
   ],
   "scripts": {
-    "build": "tsup && tsc -p tsconfig.build.json",
+    "build": "vite build && tsc -p tsconfig.build.json",
     "typecheck": "tsc --noEmit",
     "publish": "npm publish --access public"
   },