@hypawave/sdk 0.2.2 → 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,30 @@
+# Changelog
+
+All notable changes to `@hypawave/sdk` are documented here.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.3.0]
+
+### Added
+- Automatic request retries with full-jitter exponential backoff, honoring the
+  `Retry-After` header on 429 / overload responses.
+- `maxRetries` config option (default `3`; set `0` to disable retries).
+- Adaptive backoff in `waitForSettlement` (ramps from `pollInterval` up to
+  `maxPollInterval`, default 2s → 20s) instead of a fixed-interval poll.
+
+### Changed
+- Retry policy is gated by safety: every `GET` and the server-idempotent POSTs
+  (`confirmPayment`, `topup`, `getUnlockStatus`, `getOfferDownloadUrl`) retry on
+  5xx and network errors; non-idempotent POSTs (e.g. `createInvoice`) retry only
+  on 429. This prevents duplicate side effects on retry.
+- `timeout` now applies per attempt rather than to the whole call.
+- Query parameters accept `string | number | boolean | undefined`; values are
+  serialized centrally and `undefined` is omitted.
+
+### Fixed
+- Non-JSON responses (e.g. an HTML 502 from an overloaded proxy) now surface as
+  a clean `HypawaveAPIError` instead of throwing an opaque JSON parse error.
+- A successful (2xx) response with a non-JSON body now throws instead of
+  returning a malformed success object.

package/README.md

@@ -3,6 +3,7 @@
 **Bitcoin Lightning SDK for AI Agent Payments — non-custodial settlement with preimage-proof unlocks**
 
 [![npm version](https://img.shields.io/npm/v/@hypawave/sdk.svg)](https://www.npmjs.com/package/@hypawave/sdk)
+[![CI](https://github.com/hypawave/sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/hypawave/sdk/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/hypawave/sdk/blob/main/LICENSE)
 [![Node >= 18](https://img.shields.io/badge/Node-%3E%3D18-brightgreen.svg)](https://nodejs.org)
 
@@ -156,7 +157,8 @@ Both files point to two authoritative web sources so instructions stay fresh:
 |-----------|------|---------|-------------|
 | `apiKey` | `string` | — | API key (`sk_test_*` or `sk_live_*`) |
 | `baseUrl` | `string` | `https://hypawave.com` | API base URL |
-| `timeout` | `number` | `30000` | Request timeout in ms |
+| `timeout` | `number` | `30000` | Request timeout in ms (per attempt) |
+| `maxRetries` | `number` | `3` | Max automatic retries on 429 / retryable 5xx / network errors (`0` disables). Honors `Retry-After`. |
 
 ### `createInvoice(params)`
 
@@ -330,12 +332,15 @@ const { downloadUrl } = await pp.getOfferDownloadUrl(paymentIntentId, {
 
 ### `waitForSettlement(invoiceId, options?)`
 
-Poll until an invoice settles, fails, or expires.
+Poll until an invoice settles, fails, or expires. Polling backs off
+adaptively — the interval ramps from `pollInterval` up to `maxPollInterval`
+(with jitter) so a busy backend isn't hit on a fixed cadence.
 
 ```typescript
 const result = await pp.waitForSettlement(invoiceId, {
-  pollInterval: 2000,  // ms between polls (default: 2000)
-  timeout: 300000,     // max wait time in ms (default: 300000)
+  pollInterval: 2000,     // starting interval in ms (default: 2000)
+  maxPollInterval: 20000, // ceiling the interval ramps toward (default: 20000)
+  timeout: 300000,        // max wait time in ms (default: 300000)
 });
 
 if (result.unlocked) {

package/dist/index.d.mts

@@ -2,6 +2,8 @@ interface HypawaveConfig {
     apiKey: string;
     baseUrl?: string;
     timeout?: number;
+    /** Max automatic retries on 429 / retryable 5xx / network errors. Default 3. Set 0 to disable. */
+    maxRetries?: number;
 }
 interface CreateInvoiceParams {
     client_email: string;
@@ -259,6 +261,7 @@ declare class Hypawave {
     private readonly apiKey;
     private readonly baseUrl;
     private readonly timeout;
+    private readonly maxRetries;
     constructor(config: HypawaveConfig);
     private request;
     createInvoice(params: CreateInvoiceParams): Promise<CreateInvoiceResponse>;
@@ -292,6 +295,7 @@ declare class Hypawave {
     getSettings(): Promise<PublicSettingsResponse>;
     waitForSettlement(invoiceId: number, options?: {
         pollInterval?: number;
+        maxPollInterval?: number;
         timeout?: number;
     }): Promise<UnlockStatusResponse["statuses"][string]>;
     payAndConfirm(params: PayAndConfirmParams): Promise<PayAndConfirmResult>;

package/dist/index.d.ts

@@ -2,6 +2,8 @@ interface HypawaveConfig {
     apiKey: string;
     baseUrl?: string;
     timeout?: number;
+    /** Max automatic retries on 429 / retryable 5xx / network errors. Default 3. Set 0 to disable. */
+    maxRetries?: number;
 }
 interface CreateInvoiceParams {
     client_email: string;
@@ -259,6 +261,7 @@ declare class Hypawave {
     private readonly apiKey;
     private readonly baseUrl;
     private readonly timeout;
+    private readonly maxRetries;
     constructor(config: HypawaveConfig);
     private request;
     createInvoice(params: CreateInvoiceParams): Promise<CreateInvoiceResponse>;
@@ -292,6 +295,7 @@ declare class Hypawave {
     getSettings(): Promise<PublicSettingsResponse>;
     waitForSettlement(invoiceId: number, options?: {
         pollInterval?: number;
+        maxPollInterval?: number;
         timeout?: number;
     }): Promise<UnlockStatusResponse["statuses"][string]>;
     payAndConfirm(params: PayAndConfirmParams): Promise<PayAndConfirmResult>;

package/dist/index.js

@@ -51,6 +51,20 @@ var HypawaveAPIError = class extends Error {
 // src/client.ts
 var DEFAULT_BASE_URL = "https://hypawave.com";
 var DEFAULT_TIMEOUT = 3e4;
+var DEFAULT_MAX_RETRIES = 3;
+var RETRY_BASE_MS = 500;
+var RETRY_CAP_MS = 8e3;
+var sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+function backoffDelay(attempt, retryAfter) {
+  if (retryAfter) {
+    const secs = Number(retryAfter);
+    if (Number.isFinite(secs)) return Math.max(0, secs * 1e3);
+    const date = Date.parse(retryAfter);
+    if (!Number.isNaN(date)) return Math.max(0, date - Date.now());
+  }
+  const exp = Math.min(RETRY_CAP_MS, RETRY_BASE_MS * 2 ** attempt);
+  return Math.random() * exp;
+}
 async function sha256hex(hex) {
   const bytes = new Uint8Array(hex.match(/.{2}/g).map((b) => parseInt(b, 16)));
   const hash = await crypto.subtle.digest("SHA-256", bytes);
@@ -67,42 +81,71 @@ var Hypawave = class {
     this.apiKey = config.apiKey;
     this.baseUrl = (config.baseUrl || DEFAULT_BASE_URL).replace(/\/+$/, "");
     this.timeout = config.timeout ?? DEFAULT_TIMEOUT;
+    this.maxRetries = Math.max(0, config.maxRetries ?? DEFAULT_MAX_RETRIES);
   }
-  async request(method, path, body, query) {
+  async request(method, path, body, query, opts) {
     let url = `${this.baseUrl}${path}`;
     if (query) {
-      const params = new URLSearchParams(query);
-      url += `?${params.toString()}`;
-    }
-    const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), this.timeout);
-    try {
-      const res = await fetch(url, {
-        method,
-        headers: {
-          Authorization: `Bearer ${this.apiKey}`,
-          "Content-Type": "application/json",
-          Accept: "application/json"
-        },
-        body: body ? JSON.stringify(body) : void 0,
-        signal: controller.signal
-      });
-      const data = await res.json();
-      if (!res.ok) {
-        throw new HypawaveAPIError(res.status, data);
+      const params = new URLSearchParams();
+      for (const [k, v] of Object.entries(query)) {
+        if (v !== void 0) params.set(k, String(v));
       }
-      return data;
-    } catch (err) {
-      if (err instanceof HypawaveAPIError) throw err;
-      if (err instanceof DOMException && err.name === "AbortError") {
-        throw new HypawaveAPIError(408, {
-          error: "timeout",
-          message: `Request timed out after ${this.timeout}ms`
+      const qs = params.toString();
+      if (qs) url += `?${qs}`;
+    }
+    const retrySafe = opts?.retrySafe ?? method === "GET";
+    for (let attempt = 0; ; attempt++) {
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), this.timeout);
+      try {
+        const res = await fetch(url, {
+          method,
+          headers: {
+            Authorization: `Bearer ${this.apiKey}`,
+            "Content-Type": "application/json",
+            Accept: "application/json"
+          },
+          body: body ? JSON.stringify(body) : void 0,
+          signal: controller.signal
         });
+        let data;
+        let parseFailed = false;
+        try {
+          data = await res.json();
+        } catch {
+          parseFailed = true;
+          data = res.ok ? { error: "invalid_response", message: "Server returned a successful status with a non-JSON body." } : { error: `http_${res.status}`, message: `Server returned status ${res.status} with a non-JSON body.` };
+        }
+        if (!res.ok) {
+          const retryable = res.status === 429 || res.status >= 500 && retrySafe;
+          if (retryable && attempt < this.maxRetries) {
+            clearTimeout(timer);
+            await sleep(backoffDelay(attempt, res.headers.get("retry-after")));
+            continue;
+          }
+          throw new HypawaveAPIError(res.status, data);
+        }
+        if (parseFailed) {
+          throw new HypawaveAPIError(res.status, data);
+        }
+        return data;
+      } catch (err) {
+        if (err instanceof HypawaveAPIError) throw err;
+        if (err instanceof DOMException && err.name === "AbortError") {
+          throw new HypawaveAPIError(408, {
+            error: "timeout",
+            message: `Request timed out after ${this.timeout}ms`
+          });
+        }
+        if (retrySafe && attempt < this.maxRetries) {
+          clearTimeout(timer);
+          await sleep(backoffDelay(attempt, null));
+          continue;
+        }
+        throw err;
+      } finally {
+        clearTimeout(timer);
       }
-      throw err;
-    } finally {
-      clearTimeout(timer);
     }
   }
   async createInvoice(params) {
@@ -112,7 +155,9 @@ var Hypawave = class {
     return this.request("GET", "/api/paystream-cb", void 0, { token: accessToken });
   }
   async confirmPayment(invoiceId, params) {
-    return this.request("POST", `/api/invoice/${invoiceId}/confirm`, params);
+    return this.request("POST", `/api/invoice/${invoiceId}/confirm`, params, void 0, {
+      retrySafe: true
+    });
   }
   getPaymentPayload(params, response) {
     return {
@@ -145,12 +190,16 @@ var Hypawave = class {
    *   - duplicate_topup    — a pending top-up invoice already exists
    */
   async topup(_params) {
-    return this.request("POST", "/api/agent/topup", {});
+    return this.request("POST", "/api/agent/topup", {}, void 0, { retrySafe: true });
   }
   async getUnlockStatus(invoiceIds) {
-    return this.request("POST", "/api/get-unlock-status", {
-      invoice_ids: invoiceIds
-    });
+    return this.request(
+      "POST",
+      "/api/get-unlock-status",
+      { invoice_ids: invoiceIds },
+      void 0,
+      { retrySafe: true }
+    );
   }
   async getKey(invoiceFileId, token) {
     const query = { invoice_file_id: invoiceFileId };
@@ -167,16 +216,11 @@ var Hypawave = class {
     return this.request("POST", "/api/agent/store-file-key", params);
   }
   async listInvoices(params) {
-    const query = {};
-    if (params?.limit !== void 0) query.limit = String(params.limit);
-    if (params?.offset !== void 0) query.offset = String(params.offset);
-    if (params?.status) query.status = params.status;
-    return this.request(
-      "GET",
-      "/api/agent/list-invoices",
-      void 0,
-      Object.keys(query).length ? query : void 0
-    );
+    return this.request("GET", "/api/agent/list-invoices", void 0, {
+      limit: params?.limit,
+      offset: params?.offset,
+      status: params?.status
+    });
   }
   async getInvoiceFiles(invoiceIds, token) {
     const body = { invoice_ids: invoiceIds };
@@ -192,12 +236,14 @@ var Hypawave = class {
     return this.request(
       "POST",
       `/api/offers/payment-intent/${paymentIntentId}/download-url`,
-      params
+      params,
+      void 0,
+      { retrySafe: true }
     );
   }
   async getReceipt(invoiceId) {
     return this.request("GET", "/api/agent/receipt", void 0, {
-      invoice_id: String(invoiceId)
+      invoice_id: invoiceId
     });
   }
   async getPayerReceipt(invoiceId, preimage) {
@@ -209,10 +255,11 @@ var Hypawave = class {
     return this.request("GET", "/api/public-settings");
   }
   async waitForSettlement(invoiceId, options) {
-    const interval = options?.pollInterval ?? 2e3;
+    const base = options?.pollInterval ?? 2e3;
+    const maxInterval = options?.maxPollInterval ?? 2e4;
     const timeout = options?.timeout ?? 3e5;
     const start = Date.now();
-    while (Date.now() - start < timeout) {
+    for (let attempt = 0; Date.now() - start < timeout; attempt++) {
       const status = await this.getUnlockStatus([invoiceId]);
       const entry = status.statuses?.[String(invoiceId)];
       if (entry?.unlocked) {
@@ -221,7 +268,9 @@ var Hypawave = class {
       if (entry?.status === "failed" || entry?.status === "expired") {
         return entry;
       }
-      await new Promise((r) => setTimeout(r, interval));
+      const ceiling = Math.min(maxInterval, base * 2 ** attempt);
+      const wait = ceiling / 2 + Math.random() * (ceiling / 2);
+      await sleep(Math.min(wait, Math.max(0, start + timeout - Date.now())));
     }
     throw new HypawaveAPIError(408, {
       error: "settlement_timeout",

package/dist/index.mjs

@@ -24,6 +24,20 @@ var HypawaveAPIError = class extends Error {
 // src/client.ts
 var DEFAULT_BASE_URL = "https://hypawave.com";
 var DEFAULT_TIMEOUT = 3e4;
+var DEFAULT_MAX_RETRIES = 3;
+var RETRY_BASE_MS = 500;
+var RETRY_CAP_MS = 8e3;
+var sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+function backoffDelay(attempt, retryAfter) {
+  if (retryAfter) {
+    const secs = Number(retryAfter);
+    if (Number.isFinite(secs)) return Math.max(0, secs * 1e3);
+    const date = Date.parse(retryAfter);
+    if (!Number.isNaN(date)) return Math.max(0, date - Date.now());
+  }
+  const exp = Math.min(RETRY_CAP_MS, RETRY_BASE_MS * 2 ** attempt);
+  return Math.random() * exp;
+}
 async function sha256hex(hex) {
   const bytes = new Uint8Array(hex.match(/.{2}/g).map((b) => parseInt(b, 16)));
   const hash = await crypto.subtle.digest("SHA-256", bytes);
@@ -40,42 +54,71 @@ var Hypawave = class {
     this.apiKey = config.apiKey;
     this.baseUrl = (config.baseUrl || DEFAULT_BASE_URL).replace(/\/+$/, "");
     this.timeout = config.timeout ?? DEFAULT_TIMEOUT;
+    this.maxRetries = Math.max(0, config.maxRetries ?? DEFAULT_MAX_RETRIES);
   }
-  async request(method, path, body, query) {
+  async request(method, path, body, query, opts) {
     let url = `${this.baseUrl}${path}`;
     if (query) {
-      const params = new URLSearchParams(query);
-      url += `?${params.toString()}`;
-    }
-    const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), this.timeout);
-    try {
-      const res = await fetch(url, {
-        method,
-        headers: {
-          Authorization: `Bearer ${this.apiKey}`,
-          "Content-Type": "application/json",
-          Accept: "application/json"
-        },
-        body: body ? JSON.stringify(body) : void 0,
-        signal: controller.signal
-      });
-      const data = await res.json();
-      if (!res.ok) {
-        throw new HypawaveAPIError(res.status, data);
+      const params = new URLSearchParams();
+      for (const [k, v] of Object.entries(query)) {
+        if (v !== void 0) params.set(k, String(v));
       }
-      return data;
-    } catch (err) {
-      if (err instanceof HypawaveAPIError) throw err;
-      if (err instanceof DOMException && err.name === "AbortError") {
-        throw new HypawaveAPIError(408, {
-          error: "timeout",
-          message: `Request timed out after ${this.timeout}ms`
+      const qs = params.toString();
+      if (qs) url += `?${qs}`;
+    }
+    const retrySafe = opts?.retrySafe ?? method === "GET";
+    for (let attempt = 0; ; attempt++) {
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), this.timeout);
+      try {
+        const res = await fetch(url, {
+          method,
+          headers: {
+            Authorization: `Bearer ${this.apiKey}`,
+            "Content-Type": "application/json",
+            Accept: "application/json"
+          },
+          body: body ? JSON.stringify(body) : void 0,
+          signal: controller.signal
         });
+        let data;
+        let parseFailed = false;
+        try {
+          data = await res.json();
+        } catch {
+          parseFailed = true;
+          data = res.ok ? { error: "invalid_response", message: "Server returned a successful status with a non-JSON body." } : { error: `http_${res.status}`, message: `Server returned status ${res.status} with a non-JSON body.` };
+        }
+        if (!res.ok) {
+          const retryable = res.status === 429 || res.status >= 500 && retrySafe;
+          if (retryable && attempt < this.maxRetries) {
+            clearTimeout(timer);
+            await sleep(backoffDelay(attempt, res.headers.get("retry-after")));
+            continue;
+          }
+          throw new HypawaveAPIError(res.status, data);
+        }
+        if (parseFailed) {
+          throw new HypawaveAPIError(res.status, data);
+        }
+        return data;
+      } catch (err) {
+        if (err instanceof HypawaveAPIError) throw err;
+        if (err instanceof DOMException && err.name === "AbortError") {
+          throw new HypawaveAPIError(408, {
+            error: "timeout",
+            message: `Request timed out after ${this.timeout}ms`
+          });
+        }
+        if (retrySafe && attempt < this.maxRetries) {
+          clearTimeout(timer);
+          await sleep(backoffDelay(attempt, null));
+          continue;
+        }
+        throw err;
+      } finally {
+        clearTimeout(timer);
       }
-      throw err;
-    } finally {
-      clearTimeout(timer);
     }
   }
   async createInvoice(params) {
@@ -85,7 +128,9 @@ var Hypawave = class {
     return this.request("GET", "/api/paystream-cb", void 0, { token: accessToken });
   }
   async confirmPayment(invoiceId, params) {
-    return this.request("POST", `/api/invoice/${invoiceId}/confirm`, params);
+    return this.request("POST", `/api/invoice/${invoiceId}/confirm`, params, void 0, {
+      retrySafe: true
+    });
   }
   getPaymentPayload(params, response) {
     return {
@@ -118,12 +163,16 @@ var Hypawave = class {
    *   - duplicate_topup    — a pending top-up invoice already exists
    */
   async topup(_params) {
-    return this.request("POST", "/api/agent/topup", {});
+    return this.request("POST", "/api/agent/topup", {}, void 0, { retrySafe: true });
   }
   async getUnlockStatus(invoiceIds) {
-    return this.request("POST", "/api/get-unlock-status", {
-      invoice_ids: invoiceIds
-    });
+    return this.request(
+      "POST",
+      "/api/get-unlock-status",
+      { invoice_ids: invoiceIds },
+      void 0,
+      { retrySafe: true }
+    );
   }
   async getKey(invoiceFileId, token) {
     const query = { invoice_file_id: invoiceFileId };
@@ -140,16 +189,11 @@ var Hypawave = class {
     return this.request("POST", "/api/agent/store-file-key", params);
   }
   async listInvoices(params) {
-    const query = {};
-    if (params?.limit !== void 0) query.limit = String(params.limit);
-    if (params?.offset !== void 0) query.offset = String(params.offset);
-    if (params?.status) query.status = params.status;
-    return this.request(
-      "GET",
-      "/api/agent/list-invoices",
-      void 0,
-      Object.keys(query).length ? query : void 0
-    );
+    return this.request("GET", "/api/agent/list-invoices", void 0, {
+      limit: params?.limit,
+      offset: params?.offset,
+      status: params?.status
+    });
   }
   async getInvoiceFiles(invoiceIds, token) {
     const body = { invoice_ids: invoiceIds };
@@ -165,12 +209,14 @@ var Hypawave = class {
     return this.request(
       "POST",
       `/api/offers/payment-intent/${paymentIntentId}/download-url`,
-      params
+      params,
+      void 0,
+      { retrySafe: true }
     );
   }
   async getReceipt(invoiceId) {
     return this.request("GET", "/api/agent/receipt", void 0, {
-      invoice_id: String(invoiceId)
+      invoice_id: invoiceId
     });
   }
   async getPayerReceipt(invoiceId, preimage) {
@@ -182,10 +228,11 @@ var Hypawave = class {
     return this.request("GET", "/api/public-settings");
   }
   async waitForSettlement(invoiceId, options) {
-    const interval = options?.pollInterval ?? 2e3;
+    const base = options?.pollInterval ?? 2e3;
+    const maxInterval = options?.maxPollInterval ?? 2e4;
     const timeout = options?.timeout ?? 3e5;
     const start = Date.now();
-    while (Date.now() - start < timeout) {
+    for (let attempt = 0; Date.now() - start < timeout; attempt++) {
       const status = await this.getUnlockStatus([invoiceId]);
       const entry = status.statuses?.[String(invoiceId)];
       if (entry?.unlocked) {
@@ -194,7 +241,9 @@ var Hypawave = class {
       if (entry?.status === "failed" || entry?.status === "expired") {
         return entry;
       }
-      await new Promise((r) => setTimeout(r, interval));
+      const ceiling = Math.min(maxInterval, base * 2 ** attempt);
+      const wait = ceiling / 2 + Math.random() * (ceiling / 2);
+      await sleep(Math.min(wait, Math.max(0, start + timeout - Date.now())));
     }
     throw new HypawaveAPIError(408, {
       error: "settlement_timeout",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hypawave/sdk",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "description": "TypeScript SDK for Lightning settlement, preimage proof, and execution unlocks for AI agents.",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -17,10 +17,14 @@
     "skills",
     "AGENTS.md",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE"
   ],
   "scripts": {
     "build": "tsup src/index.ts --format cjs,esm --dts --clean",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
     "prepublishOnly": "npm run build"
   },
   "keywords": [
@@ -65,7 +69,8 @@
   "homepage": "https://hypawave.com/docs",
   "devDependencies": {
     "tsup": "^8.0.0",
-    "typescript": "^5.0.0"
+    "typescript": "^5.0.0",
+    "vitest": "^3.0.0"
   },
   "engines": {
     "node": ">=18"