lightnode-sdk 0.4.3 → 0.4.5

package/dist/gateway.d.ts

@@ -8,7 +8,14 @@
  * fresh-each-call thunk) by whatever means they prefer and hands it here.
  */
 import type { NetworkConfig } from "./types.js";
+/**
+ * Default gateway URL for a network. In Node, returns the gateway directly.
+ * In browser/WebContainer, returns the lightnode.app proxy (same upstream,
+ * but with permissive CORS so third-party origins work).
+ */
 export declare function consumerGatewayUrl(net: "mainnet" | "testnet"): string;
+/** Gateway host without any proxy fallback. For diagnostics / advanced callers. */
+export declare function consumerGatewayHost(net: "mainnet" | "testnet"): string;
 /** Either a fixed token, or a function that produces (or refreshes) one. */
 export type BearerSource = string | (() => string | Promise<string>);
 export declare class GatewayHttpError extends Error {

package/dist/gateway.js

@@ -11,7 +11,42 @@ const GATEWAY_HOSTS = {
     mainnet: "https://chat-api.mainnet.lightchain.ai",
     testnet: "https://chat-api.testnet.lightchain.ai",
 };
+// In browser-like contexts the gateway's CORS policy blocks third-party
+// origins, so the SDK routes through lightnode.app's public proxy instead.
+// The proxy is a thin pass-through (no state, no transformation), open to
+// any origin. In a real Node process this isn't needed - the gateway is
+// reached directly.
+const PROXY_HOSTS = {
+    mainnet: "https://lightnode.app/api/gw/mainnet",
+    testnet: "https://lightnode.app/api/gw/testnet",
+};
+/**
+ * True when the current runtime is a browser, or a Node-in-browser shim
+ * (StackBlitz WebContainer, Bolt, etc.) where `fetch` enforces browser-style
+ * CORS. Used to decide whether to call the gateway direct or via the proxy.
+ */
+function looksLikeBrowserFetch() {
+    if (typeof window !== "undefined" && typeof document !== "undefined")
+        return true;
+    // StackBlitz WebContainer exposes `process.versions.webcontainer`. Other
+    // Node-in-browser runtimes (Bolt, RunKit) may not, so we also check for
+    // the absence of a real Node TCP module via `process.versions.node` PLUS
+    // the presence of a global `WebSocket` (browser-only by spec).
+    const wc = globalThis.process?.versions?.webcontainer;
+    if (wc)
+        return true;
+    return false;
+}
+/**
+ * Default gateway URL for a network. In Node, returns the gateway directly.
+ * In browser/WebContainer, returns the lightnode.app proxy (same upstream,
+ * but with permissive CORS so third-party origins work).
+ */
 export function consumerGatewayUrl(net) {
+    return looksLikeBrowserFetch() ? PROXY_HOSTS[net] : GATEWAY_HOSTS[net];
+}
+/** Gateway host without any proxy fallback. For diagnostics / advanced callers. */
+export function consumerGatewayHost(net) {
     return GATEWAY_HOSTS[net];
 }
 async function resolveBearer(src) {

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import { NETWORKS, WORKER_REGISTRY, REGISTRY_TOPICS } from "./networks.js";
 import { fromWei } from "./subgraph.js";
 import { aggregateModelStats, aggregateWorkerStats, networkAnalytics, modelStatsCsv, workerStatsCsv, workerJobsCsv } from "./analytics.js";
-import { modelId as computeModelId, estimateJobFee, JOB_REGISTRY_CONSUMER_ABI, consumerGatewayUrl, prepareSession, submitPrompt, decryptResponse, generateEcdhKeyPair, runInference, runInferenceWithKey } from "./inference.js";
+import { modelId as computeModelId, estimateJobFee, JOB_REGISTRY_CONSUMER_ABI, consumerGatewayUrl, consumerGatewayHost, prepareSession, submitPrompt, decryptResponse, generateEcdhKeyPair, runInference, runInferenceWithKey } from "./inference.js";
 import { StalledWorkerError, OnChainRevertError, RelayTokenTimeoutError, GatewayAuthError, isStalledWorker } from "./errors.js";
 import { GatewayClient, GatewayHttpError } from "./gateway.js";
 import * as crypto from "./crypto.js";
@@ -60,7 +60,7 @@ export declare class LightNode {
         baseUrl?: string;
     }): GatewayClient;
 }
-export { NETWORKS, WORKER_REGISTRY, REGISTRY_TOPICS, aggregateModelStats, aggregateWorkerStats, networkAnalytics, modelStatsCsv, workerStatsCsv, workerJobsCsv, fromWei, computeModelId as modelId, estimateJobFee, JOB_REGISTRY_CONSUMER_ABI, consumerGatewayUrl, GatewayClient, GatewayHttpError, prepareSession, submitPrompt, decryptResponse, generateEcdhKeyPair, crypto, runInference, runInferenceWithKey, StalledWorkerError, OnChainRevertError, RelayTokenTimeoutError, GatewayAuthError, isStalledWorker, };
+export { NETWORKS, WORKER_REGISTRY, REGISTRY_TOPICS, aggregateModelStats, aggregateWorkerStats, networkAnalytics, modelStatsCsv, workerStatsCsv, workerJobsCsv, fromWei, computeModelId as modelId, estimateJobFee, JOB_REGISTRY_CONSUMER_ABI, consumerGatewayUrl, consumerGatewayHost, GatewayClient, GatewayHttpError, prepareSession, submitPrompt, decryptResponse, generateEcdhKeyPair, crypto, runInference, runInferenceWithKey, StalledWorkerError, OnChainRevertError, RelayTokenTimeoutError, GatewayAuthError, isStalledWorker, };
 export type { BearerSource, GatewayClientOptions, SelectSessionResult, PrepareSessionResult, UploadBlobResult, SessionTokenResult } from "./gateway.js";
 export type { SessionPreparation, RunInferenceArgs, RunInferenceResult, RunInferenceWithKeyArgs } from "./inference.js";
 export type { NetworkId, NetworkConfig, Worker, Job, ModelInfo, NetworkStats, ModelStat, WorkerStat, NetworkAnalytics };

package/dist/index.js

@@ -2,7 +2,7 @@ import { NETWORKS, WORKER_REGISTRY, REGISTRY_TOPICS } from "./networks.js";
 import { fetchWorker, fetchWorkerJobs, fetchRecentJobs, fetchModels, fetchWorkers, summarize, fromWei, } from "./subgraph.js";
 import { isRegistered } from "./onchain.js";
 import { aggregateModelStats, aggregateWorkerStats, networkAnalytics, modelStatsCsv, workerStatsCsv, workerJobsCsv, } from "./analytics.js";
-import { modelId as computeModelId, estimateJobFee, JOB_REGISTRY_CONSUMER_ABI, consumerGatewayUrl, prepareSession, submitPrompt, decryptResponse, generateEcdhKeyPair, runInference, runInferenceWithKey, } from "./inference.js";
+import { modelId as computeModelId, estimateJobFee, JOB_REGISTRY_CONSUMER_ABI, consumerGatewayUrl, consumerGatewayHost, prepareSession, submitPrompt, decryptResponse, generateEcdhKeyPair, runInference, runInferenceWithKey, } from "./inference.js";
 import { StalledWorkerError, OnChainRevertError, RelayTokenTimeoutError, GatewayAuthError, isStalledWorker, } from "./errors.js";
 import { GatewayClient, GatewayHttpError } from "./gateway.js";
 import * as crypto from "./crypto.js";
@@ -90,7 +90,7 @@ export class LightNode {
         return new GatewayClient({ network: this.network, ...opts });
     }
 }
-export { NETWORKS, WORKER_REGISTRY, REGISTRY_TOPICS, aggregateModelStats, aggregateWorkerStats, networkAnalytics, modelStatsCsv, workerStatsCsv, workerJobsCsv, fromWei, computeModelId as modelId, estimateJobFee, JOB_REGISTRY_CONSUMER_ABI, consumerGatewayUrl, 
+export { NETWORKS, WORKER_REGISTRY, REGISTRY_TOPICS, aggregateModelStats, aggregateWorkerStats, networkAnalytics, modelStatsCsv, workerStatsCsv, workerJobsCsv, fromWei, computeModelId as modelId, estimateJobFee, JOB_REGISTRY_CONSUMER_ABI, consumerGatewayUrl, consumerGatewayHost, 
 // v0.3 inference-submit surface (BETA - see README "Submitting inference").
 GatewayClient, GatewayHttpError, prepareSession, submitPrompt, decryptResponse, generateEcdhKeyPair, crypto, 
 // v0.4 high-level orchestrator: one call, full flow.

package/dist/inference.d.ts

@@ -91,7 +91,7 @@ export declare function submitPrompt(gateway: GatewayClient, sessionKey: Uint8Ar
 /** Decrypt a worker response (raw bytes or base64 from the relay) with the session key. */
 export declare function decryptResponse(sessionKey: Uint8Array, ciphertext: Uint8Array | string): Promise<string>;
 /** Re-export so callers don't have to import from a second module just for the URL helper. */
-export { consumerGatewayUrl, GatewayClient } from "./gateway.js";
+export { consumerGatewayUrl, consumerGatewayHost, GatewayClient } from "./gateway.js";
 /** Optional helper: generate the caller's own ECDH keypair if they want one (e.g. acting as the disputer). */
 export { generateEcdhKeyPair };
 interface MinimalWalletClient {

package/dist/inference.js

@@ -123,7 +123,7 @@ export async function decryptResponse(sessionKey, ciphertext) {
     return bytesToUtf8(await decrypt(sessionKey, bytes));
 }
 /** Re-export so callers don't have to import from a second module just for the URL helper. */
-export { consumerGatewayUrl, GatewayClient } from "./gateway.js";
+export { consumerGatewayUrl, consumerGatewayHost, GatewayClient } from "./gateway.js";
 /** Optional helper: generate the caller's own ECDH keypair if they want one (e.g. acting as the disputer). */
 export { generateEcdhKeyPair };
 // ----------------------------------------------------------------------------
@@ -326,16 +326,31 @@ async function runOneAttempt(args, attempt) {
         throw new Error("JobSubmitted log missing in submitJob receipt");
     const jobId = topicAsUint(jobLog.topics[1]);
     // 6. wait for JobCompleted
-    // KEY INVARIANT: the real result is the WS-delivered, session-key-decrypted
-    // ciphertext. JobCompleted is an explorer pointer (the worker's commit-result
-    // tx). If the WS already produced an answer (chunks.length > 0) we MUST
-    // accept it even if the on-chain event hasn't landed - throwing stalled here
-    // wipes a delivered answer on retry, which reads as "the call returned nothing".
+    // The actual *result* is the WS-delivered, session-key-decrypted ciphertext.
+    // JobCompleted is an explorer pointer (the worker's commit-result tx).
+    // Polling rules:
+    //   - No chunks yet: poll for the full deadline (default 120s). Still nothing
+    //     -> throw stalled so the outer loop can retry with a different worker.
+    //   - Chunks arrived: keep polling for a 45s grace window after the FIRST
+    //     chunk. Workers usually commit JobCompleted within ~10s of broadcasting
+    //     the answer, so 45s is generous. If it still doesn't land, surface the
+    //     answer with txs.jobCompleted=null (the answer is still session-key
+    //     authentic; the on-chain proof can be polled for separately by callers).
     const deadline = Date.now() + jobCompletedTimeoutMs;
+    const POST_CHUNKS_GRACE_MS = 45000;
+    const waitStart = Date.now();
+    let firstChunkAt = chunks.length > 0 ? waitStart : null;
     const jobIdTopic = (`0x${jobId.toString(16).padStart(64, "0")}`);
     let completed = null;
-    while (!completed && Date.now() < deadline) {
+    while (!completed) {
+        const now = Date.now();
+        if (now >= deadline)
+            break;
+        if (firstChunkAt != null && now - firstChunkAt >= POST_CHUNKS_GRACE_MS)
+            break;
         await new Promise((res) => setTimeout(res, 3000));
+        if (firstChunkAt == null && chunks.length > 0)
+            firstChunkAt = Date.now();
         const logs = await publicClient.getLogs({
             address: network.jobRegistry,
             fromBlock: submitReceipt.blockNumber,
@@ -345,10 +360,6 @@ async function runOneAttempt(args, attempt) {
             logs.find((l) => l.topics[0] === JOB_COMPLETED_TOPIC && l.topics[1] === jobIdTopic) ?? null;
         if (completed)
             break;
-        // If the WS already delivered the answer, stop polling - no point burning
-        // more time on a confirmation that only serves as an explorer link.
-        if (chunks.length > 0)
-            break;
     }
     if (!completed && chunks.length === 0) {
         try {
@@ -486,26 +497,44 @@ export async function runInferenceWithKey(args) {
     // the caller doesn't need a second import; in browsers + Node it works the
     // same against the consumer-api gateway.
     const gwBase = args.gatewayUrl ?? consumerGatewayUrlFn(networkId);
-    const chRes = await fetch(`${gwBase}/api/auth/challenge?address=${account.address}`, {
-        headers: { Accept: "application/json" },
-    });
+    // `fetch failed` with no cause is the worst possible error for a builder
+    // running this for the first time - they need to know which host failed and
+    // what the underlying cause was. Wrap both SIWE calls so the error names a
+    // host (so a network/DNS/CORS problem is obvious) and a hint when the cause
+    // looks like a CORS or undici-level reachability error.
+    const fetchOrFail = async (url, init, label) => {
+        try {
+            return await fetch(url, init);
+        }
+        catch (err) {
+            const cause = err.cause;
+            const code = cause?.code ?? "";
+            const msg = err.message ?? "fetch failed";
+            const detail = cause?.message ? ` (${cause.message})` : "";
+            const hint = /ENOTFOUND|EAI_AGAIN|ECONNREFUSED|UND_ERR_CONNECT|CERT_/.test(code) || msg.includes("CORS")
+                ? ` Tip: this host may be unreachable from this runtime (CORS, DNS, or TLS). Pass gatewayUrl: 'https://lightnode.app/api/gw/${networkId}' to route through the public proxy.`
+                : "";
+            throw new Error(`SIWE ${label ?? "request"} to ${url} failed: ${msg}${detail}${hint}`);
+        }
+    };
+    const chRes = await fetchOrFail(`${gwBase}/api/auth/challenge?address=${account.address}`, { headers: { Accept: "application/json" } }, "challenge");
     if (!chRes.ok)
         throw new GatewayAuthError(chRes.status, await chRes.text());
     const ch = (await chRes.json());
     if (!ch.message)
         throw new GatewayAuthError(chRes.status, "auth challenge returned no message");
     const signature = await wallet.signMessage({ account, message: ch.message });
-    const verifyRes = await fetch(`${gwBase}/api/auth/verify`, {
+    const verifyRes = await fetchOrFail(`${gwBase}/api/auth/verify`, {
         method: "POST",
         headers: { "Content-Type": "application/json", Accept: "application/json" },
         body: JSON.stringify({ message: ch.message, signature }),
-    });
+    }, "verify");
     if (!verifyRes.ok)
         throw new GatewayAuthError(verifyRes.status, await verifyRes.text());
     const verify = (await verifyRes.json());
     if (!verify.token)
         throw new GatewayAuthError(verifyRes.status, "auth verify returned no token");
-    const gateway = new GatewayClientCtor({ network: networkId, bearer: verify.token, baseUrl: args.gatewayUrl });
+    const gateway = new GatewayClientCtor({ network: networkId, bearer: verify.token, baseUrl: args.gatewayUrl ?? gwBase });
     // Pick a WebSocket: the browser global if present, otherwise the caller-
     // supplied ctor. We deliberately do NOT try to dynamic-import "ws" - it
     // isn't a hard dep, and a bundler trying to resolve it would fail noisily.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lightnode-sdk",
-  "version": "0.4.3",
+  "version": "0.4.5",
   "description": "Read-only TypeScript client for LightChain AI: workers, jobs, models, on-chain registration, and per-model network analytics. Independent, community-built (not an official LightChain package).",
   "type": "module",
   "main": "./dist/index.js",