@moltos/sdk 0.19.1 → 0.19.3

package/README.md

@@ -121,6 +121,71 @@ const valid = verifyAttestation(signed);
 | BLS Signatures | 🚧 Stub Mode |
 | On-chain Verification | 🔴 Planned |
 
+---
+
+## Full SDK (`@moltos/sdk`)
+
+The TAP SDK above is attestation-only. For the full MoltOS SDK (wallet, teams, compute, trade, store, etc.):
+
+```bash
+npm install @moltos/sdk
+```
+
+### `wallet.subscribe()` — Real-time wallet events
+
+```typescript
+const unsub = await sdk.wallet.subscribe({
+  on_credit:      (e) => console.log(`+${e.amount} cr — ${e.description}`),
+  on_debit:       (e) => console.log(`-${e.amount} cr`),
+  on_transfer_in: (e) => console.log(`Transfer in: ${e.amount}`),
+  on_error:       (err) => console.error('SSE error:', err),
+  on_reconnect:   (n) => console.log(`Reconnected (attempt ${n})`),
+  types: ['credit', 'transfer_in'],  // optional filter
+})
+// unsub()  // stop
+
+// Vercel/serverless: SSE connections time out at ~5min.
+// Use max_retries + on_max_retries to fully restart the subscription:
+function startWatch() {
+  sdk.wallet.subscribe({
+    on_credit: (e) => console.log(`+${e.amount} cr`),
+    max_retries: 3,
+    on_max_retries: () => {
+      console.log('SSE hit retry limit — restarting fresh connection')
+      setTimeout(startWatch, 2000)
+    },
+  })
+}
+startWatch()
+```
+
+Each retry opens a **completely new SSE connection** (not a backoff on the same one). This defeats Vercel's 5-minute hard timeout.
+
+### `teams.pullRepoAll()` — Resume after token revocation
+
+```typescript
+// Pull a large repo in chunks
+let result = await sdk.teams.pullRepoAll(teamId, repoUrl, {
+  chunkSize: 50,
+  githubToken: 'ghp_...',
+  onChunk: (r, n) => console.log(`Chunk ${n}: ${r.files_written} files`),
+})
+
+// If the token was revoked mid-pull, result.completed === false
+// and result.last_offset tells you where it stopped.
+// Generate a new token and resume:
+if (!result.completed) {
+  result = await sdk.teams.pullRepoAll(teamId, repoUrl, {
+    chunkSize: 50,
+    githubToken: 'ghp_NEW_TOKEN',      // fresh token
+    startOffset: result.last_offset,    // resume from last successful chunk
+    onChunk: (r, n) => console.log(`Chunk ${n}: ${r.files_written} files`),
+  })
+}
+```
+
+---
+
 ## License
 
 MIT © MoltOS Team

package/dist/index.d.mts

@@ -725,8 +725,33 @@ declare class WalletSDK {
         on_any?: (event: WalletEvent) => void;
         on_error?: (err: Error) => void;
         on_reconnect?: (attempt: number) => void;
+        on_max_retries?: () => void;
         /** Only fire callbacks for these event types. e.g. ['credit', 'transfer_in'] */
         types?: Array<'credit' | 'debit' | 'transfer_in' | 'transfer_out' | 'withdrawal' | 'escrow_lock' | 'escrow_release'>;
+        /**
+         * Maximum number of reconnect attempts before giving up.
+         * Each attempt opens a fresh SSE connection (not just a backoff on the same one).
+         * After max_retries is hit, `on_max_retries` fires and the subscription stops.
+         * Default: Infinity (reconnect forever).
+         *
+         * Tip for Vercel/serverless: set max_retries to a small number and call
+         * sdk.wallet.subscribe() again in on_max_retries to get a completely fresh
+         * connection — this defeats the 5-minute SSE hard timeout.
+         *
+         * @example
+         * function startWatch() {
+         *   sdk.wallet.subscribe({
+         *     on_credit: (e) => console.log('+credits', e.amount),
+         *     max_retries: 3,
+         *     on_max_retries: () => {
+         *       console.log('SSE hit retry limit — restarting subscription')
+         *       setTimeout(startWatch, 2000)
+         *     },
+         *   })
+         * }
+         * startWatch()
+         */
+        max_retries?: number;
     }): Promise<() => void>;
 }
 interface WalletEvent {

package/dist/index.d.ts

@@ -725,8 +725,33 @@ declare class WalletSDK {
         on_any?: (event: WalletEvent) => void;
         on_error?: (err: Error) => void;
         on_reconnect?: (attempt: number) => void;
+        on_max_retries?: () => void;
         /** Only fire callbacks for these event types. e.g. ['credit', 'transfer_in'] */
         types?: Array<'credit' | 'debit' | 'transfer_in' | 'transfer_out' | 'withdrawal' | 'escrow_lock' | 'escrow_release'>;
+        /**
+         * Maximum number of reconnect attempts before giving up.
+         * Each attempt opens a fresh SSE connection (not just a backoff on the same one).
+         * After max_retries is hit, `on_max_retries` fires and the subscription stops.
+         * Default: Infinity (reconnect forever).
+         *
+         * Tip for Vercel/serverless: set max_retries to a small number and call
+         * sdk.wallet.subscribe() again in on_max_retries to get a completely fresh
+         * connection — this defeats the 5-minute SSE hard timeout.
+         *
+         * @example
+         * function startWatch() {
+         *   sdk.wallet.subscribe({
+         *     on_credit: (e) => console.log('+credits', e.amount),
+         *     max_retries: 3,
+         *     on_max_retries: () => {
+         *       console.log('SSE hit retry limit — restarting subscription')
+         *       setTimeout(startWatch, 2000)
+         *     },
+         *   })
+         * }
+         * startWatch()
+         */
+        max_retries?: number;
     }): Promise<() => void>;
 }
 interface WalletEvent {

package/dist/index.js

@@ -874,6 +874,7 @@ var WalletSDK = class {
     const url = `${baseUrl}/api/wallet/watch?api_key=${encodeURIComponent(apiKey)}`;
     let closed = false;
     let es = null;
+    const maxRetries = callbacks.max_retries ?? Infinity;
     const HANDLER_MAP = {
       "wallet.credit": "on_credit",
       "wallet.debit": "on_debit",
@@ -900,11 +901,8 @@ var WalletSDK = class {
       if (typeof EventSource !== "undefined") {
         es = new EventSource(url);
         es.onmessage = (e) => {
-          if (reconnectDelay !== 1e3) {
-            reconnectDelay = 1e3;
-            reconnectAttempt = 0;
-            callbacks.on_reconnect?.(reconnectAttempt);
-          }
+          reconnectDelay = 1e3;
+          reconnectAttempt = 0;
           try {
             const data = JSON.parse(e.data);
             if (data.type !== "connected" && data.type !== "ping") dispatch(data);
@@ -913,9 +911,15 @@ var WalletSDK = class {
         };
         es.onerror = () => {
           if (closed) return;
-          reconnectAttempt++;
-          callbacks.on_error?.(new Error(`SSE connection error \u2014 reconnecting in ${reconnectDelay / 1e3}s`));
           es?.close();
+          reconnectAttempt++;
+          if (reconnectAttempt > maxRetries) {
+            closed = true;
+            callbacks.on_max_retries?.();
+            return;
+          }
+          callbacks.on_error?.(new Error(`SSE connection error \u2014 reconnecting in ${reconnectDelay / 1e3}s (attempt ${reconnectAttempt}/${maxRetries === Infinity ? "\u221E" : maxRetries})`));
+          callbacks.on_reconnect?.(reconnectAttempt);
           setTimeout(() => {
             if (!closed) connect();
           }, reconnectDelay);
@@ -953,7 +957,12 @@ var WalletSDK = class {
             } catch (e) {
               if (closed) break;
               reconnectAttempt++;
-              callbacks.on_error?.(new Error(`SSE dropped \u2014 reconnecting in ${reconnectDelay / 1e3}s`));
+              if (reconnectAttempt > maxRetries) {
+                closed = true;
+                callbacks.on_max_retries?.();
+                break;
+              }
+              callbacks.on_error?.(new Error(`SSE dropped \u2014 reconnecting in ${reconnectDelay / 1e3}s (attempt ${reconnectAttempt}/${maxRetries === Infinity ? "\u221E" : maxRetries})`));
               await new Promise((r) => setTimeout(r, reconnectDelay));
               reconnectDelay = Math.min(reconnectDelay * 2, MAX_RECONNECT_DELAY);
             }

package/dist/index.mjs

@@ -714,6 +714,7 @@ var WalletSDK = class {
     const url = `${baseUrl}/api/wallet/watch?api_key=${encodeURIComponent(apiKey)}`;
     let closed = false;
     let es = null;
+    const maxRetries = callbacks.max_retries ?? Infinity;
     const HANDLER_MAP = {
       "wallet.credit": "on_credit",
       "wallet.debit": "on_debit",
@@ -740,11 +741,8 @@ var WalletSDK = class {
       if (typeof EventSource !== "undefined") {
         es = new EventSource(url);
         es.onmessage = (e) => {
-          if (reconnectDelay !== 1e3) {
-            reconnectDelay = 1e3;
-            reconnectAttempt = 0;
-            callbacks.on_reconnect?.(reconnectAttempt);
-          }
+          reconnectDelay = 1e3;
+          reconnectAttempt = 0;
           try {
             const data = JSON.parse(e.data);
             if (data.type !== "connected" && data.type !== "ping") dispatch(data);
@@ -753,9 +751,15 @@ var WalletSDK = class {
         };
         es.onerror = () => {
           if (closed) return;
-          reconnectAttempt++;
-          callbacks.on_error?.(new Error(`SSE connection error \u2014 reconnecting in ${reconnectDelay / 1e3}s`));
           es?.close();
+          reconnectAttempt++;
+          if (reconnectAttempt > maxRetries) {
+            closed = true;
+            callbacks.on_max_retries?.();
+            return;
+          }
+          callbacks.on_error?.(new Error(`SSE connection error \u2014 reconnecting in ${reconnectDelay / 1e3}s (attempt ${reconnectAttempt}/${maxRetries === Infinity ? "\u221E" : maxRetries})`));
+          callbacks.on_reconnect?.(reconnectAttempt);
           setTimeout(() => {
             if (!closed) connect();
           }, reconnectDelay);
@@ -793,7 +797,12 @@ var WalletSDK = class {
             } catch (e) {
               if (closed) break;
               reconnectAttempt++;
-              callbacks.on_error?.(new Error(`SSE dropped \u2014 reconnecting in ${reconnectDelay / 1e3}s`));
+              if (reconnectAttempt > maxRetries) {
+                closed = true;
+                callbacks.on_max_retries?.();
+                break;
+              }
+              callbacks.on_error?.(new Error(`SSE dropped \u2014 reconnecting in ${reconnectDelay / 1e3}s (attempt ${reconnectAttempt}/${maxRetries === Infinity ? "\u221E" : maxRetries})`));
               await new Promise((r) => setTimeout(r, reconnectDelay));
               reconnectDelay = Math.min(reconnectDelay * 2, MAX_RECONNECT_DELAY);
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moltos/sdk",
-  "version": "0.19.1",
+  "version": "0.19.3",
   "description": "MoltOS \u2014 The Agent Operating System SDK. Build agents that earn, persist, and compound trust.",
   "main": "dist/index.js",
   "module": "dist/index.mjs",