@hypawave/sdk 0.1.0

package/dist/index.js

@@ -0,0 +1,279 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  Hypawave: () => Hypawave,
+  HypawaveAPIError: () => HypawaveAPIError
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/errors.ts
+var HypawaveAPIError = class extends Error {
+  constructor(status, body) {
+    super(body.message || body.error);
+    this.name = "HypawaveAPIError";
+    this.status = status;
+    this.code = body.error;
+    this.field = body.field;
+  }
+  get isAuth() {
+    return this.status === 401;
+  }
+  get isRateLimit() {
+    return this.status === 429;
+  }
+  get isValidation() {
+    return this.code === "validation_error";
+  }
+  get isOutstandingFee() {
+    return this.status === 402;
+  }
+};
+
+// src/client.ts
+var DEFAULT_BASE_URL = "https://hypawave.com";
+var DEFAULT_TIMEOUT = 3e4;
+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);
+  return Array.from(new Uint8Array(hash)).map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+var Hypawave = class {
+  constructor(config) {
+    if (!config.apiKey) {
+      throw new Error("apiKey is required");
+    }
+    if (!/^sk_(test|live)_.+/.test(config.apiKey)) {
+      throw new Error('apiKey must start with "sk_test_" or "sk_live_"');
+    }
+    this.apiKey = config.apiKey;
+    this.baseUrl = (config.baseUrl || DEFAULT_BASE_URL).replace(/\/+$/, "");
+    this.timeout = config.timeout ?? DEFAULT_TIMEOUT;
+  }
+  async request(method, path, body, query) {
+    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);
+      }
+      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`
+        });
+      }
+      throw err;
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+  async createInvoice(params) {
+    return this.request("POST", "/api/agent/create-invoice", params);
+  }
+  async getBolt11(accessToken) {
+    return this.request("GET", "/api/paystream-cb", void 0, { token: accessToken });
+  }
+  async confirmPayment(invoiceId, params) {
+    return this.request("POST", `/api/invoice/${invoiceId}/confirm`, params);
+  }
+  getPaymentPayload(params, response) {
+    return {
+      protocol: "hypawave/v1",
+      invoice_id: response.invoice_id,
+      amount: response.amount,
+      currency: response.currency,
+      sats: response.sats,
+      btc_usd_rate: response.btc_usd_rate,
+      description: params.description ?? null,
+      expires_at: response.expires_at,
+      bolt11_url: `${this.baseUrl}/api/paystream-cb?token=${response.access_token}`,
+      confirm_url: `${this.baseUrl}/api/invoice/${response.invoice_id}/confirm`,
+      payment_url: response.payment_url,
+      spec_url: `${this.baseUrl}/.well-known/openapi.json`,
+      instructions_url: `${this.baseUrl}/llms.txt`
+    };
+  }
+  async getBalance(currency) {
+    const query = currency ? { currency } : void 0;
+    return this.request("GET", "/api/agent/balance", void 0, query);
+  }
+  /**
+   * Request a fee-settlement top-up invoice. The server mints a bolt11 for
+   * exactly the amount owed — balance can never exceed 0. No arguments are
+   * needed; any amount fields in a passed params object are ignored.
+   *
+   * Throws API errors:
+   *   - topup_not_needed   — balance is already ≥ 0
+   *   - duplicate_topup    — a pending top-up invoice already exists
+   */
+  async topup(_params) {
+    return this.request("POST", "/api/agent/topup", {});
+  }
+  async getUnlockStatus(invoiceIds) {
+    return this.request("POST", "/api/get-unlock-status", {
+      invoice_ids: invoiceIds
+    });
+  }
+  async getKey(invoiceFileId, token) {
+    const query = { invoice_file_id: invoiceFileId };
+    if (token) query.token = token;
+    return this.request("GET", "/api/get-key", void 0, query);
+  }
+  async getUploadUrl(params) {
+    return this.request("POST", "/api/agent/upload-url", params);
+  }
+  async storeFile(params) {
+    return this.request("POST", "/api/agent/store-file", params);
+  }
+  async storeFileKey(params) {
+    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
+    );
+  }
+  async getInvoiceFiles(invoiceIds, token) {
+    const body = { invoice_ids: invoiceIds };
+    if (token) body.token = token;
+    return this.request("POST", "/api/get-invoice-files", body);
+  }
+  async getDownloadUrl(invoiceFileId, token) {
+    const body = { invoice_file_id: invoiceFileId };
+    if (token) body.token = token;
+    return this.request("POST", "/api/generate-download-url", body);
+  }
+  async getOfferDownloadUrl(paymentIntentId, params) {
+    return this.request(
+      "POST",
+      `/api/offers/payment-intent/${paymentIntentId}/download-url`,
+      params
+    );
+  }
+  async getReceipt(invoiceId) {
+    return this.request("GET", "/api/agent/receipt", void 0, {
+      invoice_id: String(invoiceId)
+    });
+  }
+  async getPayerReceipt(invoiceId, preimage) {
+    return this.request("GET", `/api/invoice/${invoiceId}/receipt`, void 0, {
+      preimage
+    });
+  }
+  async getSettings() {
+    return this.request("GET", "/api/public-settings");
+  }
+  async waitForSettlement(invoiceId, options) {
+    const interval = options?.pollInterval ?? 2e3;
+    const timeout = options?.timeout ?? 3e5;
+    const start = Date.now();
+    while (Date.now() - start < timeout) {
+      const status = await this.getUnlockStatus([invoiceId]);
+      const entry = status.statuses?.[String(invoiceId)];
+      if (entry?.unlocked) {
+        return entry;
+      }
+      if (entry?.status === "failed" || entry?.status === "expired") {
+        return entry;
+      }
+      await new Promise((r) => setTimeout(r, interval));
+    }
+    throw new HypawaveAPIError(408, {
+      error: "settlement_timeout",
+      message: `Settlement not confirmed within ${timeout}ms`
+    });
+  }
+  async payAndConfirm(params) {
+    const capability = params.wallet.capabilities?.returnsPreimage;
+    if (capability === false || capability === void 0) {
+      throw new HypawaveAPIError(400, {
+        error: "wallet_no_preimage_support",
+        message: "This wallet does not support returning the preimage. Hypawave requires the preimage for settlement confirmation. Use a supported adapter (NWC, LND, CLN, Alby, LNbits) from @hypawave/lightning-adapters."
+      });
+    }
+    if (capability === "conditional" && !params.allowConditionalPreimage) {
+      throw new HypawaveAPIError(400, {
+        error: "wallet_conditional_preimage",
+        message: "This wallet conditionally supports preimage return (depends on the backing node). Set allowConditionalPreimage: true to proceed at your own risk. If the preimage is not returned after payment, files will not unlock."
+      });
+    }
+    const { pr: bolt11, terms_hash } = await this.getBolt11(params.accessToken);
+    const payResult = await params.wallet.payInvoice(bolt11);
+    if (!payResult.preimage || !/^[0-9a-f]{64}$/i.test(payResult.preimage)) {
+      throw new HypawaveAPIError(400, {
+        error: "wallet_did_not_return_preimage",
+        message: "Wallet did not return a valid preimage. Hypawave requires a 64-char hex preimage for settlement confirmation."
+      });
+    }
+    const computedHash = await sha256hex(payResult.preimage);
+    if (payResult.payment_hash && computedHash.toLowerCase() !== payResult.payment_hash.toLowerCase()) {
+      throw new HypawaveAPIError(400, {
+        error: "preimage_hash_mismatch",
+        message: `Client-side verification failed: SHA256(preimage) does not match payment_hash. Expected ${payResult.payment_hash}, got ${computedHash}.`
+      });
+    }
+    const paymentHash = payResult.payment_hash || computedHash;
+    const confirmation = await this.confirmPayment(params.invoiceId, {
+      payment_hash: paymentHash,
+      preimage: payResult.preimage,
+      terms_hash
+    });
+    return {
+      payment_hash: paymentHash,
+      preimage: payResult.preimage,
+      terms_hash,
+      fees_paid_msat: payResult.fees_paid_msat,
+      confirmation
+    };
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Hypawave,
+  HypawaveAPIError
+});

package/dist/index.mjs

@@ -0,0 +1,251 @@
+// src/errors.ts
+var HypawaveAPIError = class extends Error {
+  constructor(status, body) {
+    super(body.message || body.error);
+    this.name = "HypawaveAPIError";
+    this.status = status;
+    this.code = body.error;
+    this.field = body.field;
+  }
+  get isAuth() {
+    return this.status === 401;
+  }
+  get isRateLimit() {
+    return this.status === 429;
+  }
+  get isValidation() {
+    return this.code === "validation_error";
+  }
+  get isOutstandingFee() {
+    return this.status === 402;
+  }
+};
+
+// src/client.ts
+var DEFAULT_BASE_URL = "https://hypawave.com";
+var DEFAULT_TIMEOUT = 3e4;
+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);
+  return Array.from(new Uint8Array(hash)).map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+var Hypawave = class {
+  constructor(config) {
+    if (!config.apiKey) {
+      throw new Error("apiKey is required");
+    }
+    if (!/^sk_(test|live)_.+/.test(config.apiKey)) {
+      throw new Error('apiKey must start with "sk_test_" or "sk_live_"');
+    }
+    this.apiKey = config.apiKey;
+    this.baseUrl = (config.baseUrl || DEFAULT_BASE_URL).replace(/\/+$/, "");
+    this.timeout = config.timeout ?? DEFAULT_TIMEOUT;
+  }
+  async request(method, path, body, query) {
+    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);
+      }
+      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`
+        });
+      }
+      throw err;
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+  async createInvoice(params) {
+    return this.request("POST", "/api/agent/create-invoice", params);
+  }
+  async getBolt11(accessToken) {
+    return this.request("GET", "/api/paystream-cb", void 0, { token: accessToken });
+  }
+  async confirmPayment(invoiceId, params) {
+    return this.request("POST", `/api/invoice/${invoiceId}/confirm`, params);
+  }
+  getPaymentPayload(params, response) {
+    return {
+      protocol: "hypawave/v1",
+      invoice_id: response.invoice_id,
+      amount: response.amount,
+      currency: response.currency,
+      sats: response.sats,
+      btc_usd_rate: response.btc_usd_rate,
+      description: params.description ?? null,
+      expires_at: response.expires_at,
+      bolt11_url: `${this.baseUrl}/api/paystream-cb?token=${response.access_token}`,
+      confirm_url: `${this.baseUrl}/api/invoice/${response.invoice_id}/confirm`,
+      payment_url: response.payment_url,
+      spec_url: `${this.baseUrl}/.well-known/openapi.json`,
+      instructions_url: `${this.baseUrl}/llms.txt`
+    };
+  }
+  async getBalance(currency) {
+    const query = currency ? { currency } : void 0;
+    return this.request("GET", "/api/agent/balance", void 0, query);
+  }
+  /**
+   * Request a fee-settlement top-up invoice. The server mints a bolt11 for
+   * exactly the amount owed — balance can never exceed 0. No arguments are
+   * needed; any amount fields in a passed params object are ignored.
+   *
+   * Throws API errors:
+   *   - topup_not_needed   — balance is already ≥ 0
+   *   - duplicate_topup    — a pending top-up invoice already exists
+   */
+  async topup(_params) {
+    return this.request("POST", "/api/agent/topup", {});
+  }
+  async getUnlockStatus(invoiceIds) {
+    return this.request("POST", "/api/get-unlock-status", {
+      invoice_ids: invoiceIds
+    });
+  }
+  async getKey(invoiceFileId, token) {
+    const query = { invoice_file_id: invoiceFileId };
+    if (token) query.token = token;
+    return this.request("GET", "/api/get-key", void 0, query);
+  }
+  async getUploadUrl(params) {
+    return this.request("POST", "/api/agent/upload-url", params);
+  }
+  async storeFile(params) {
+    return this.request("POST", "/api/agent/store-file", params);
+  }
+  async storeFileKey(params) {
+    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
+    );
+  }
+  async getInvoiceFiles(invoiceIds, token) {
+    const body = { invoice_ids: invoiceIds };
+    if (token) body.token = token;
+    return this.request("POST", "/api/get-invoice-files", body);
+  }
+  async getDownloadUrl(invoiceFileId, token) {
+    const body = { invoice_file_id: invoiceFileId };
+    if (token) body.token = token;
+    return this.request("POST", "/api/generate-download-url", body);
+  }
+  async getOfferDownloadUrl(paymentIntentId, params) {
+    return this.request(
+      "POST",
+      `/api/offers/payment-intent/${paymentIntentId}/download-url`,
+      params
+    );
+  }
+  async getReceipt(invoiceId) {
+    return this.request("GET", "/api/agent/receipt", void 0, {
+      invoice_id: String(invoiceId)
+    });
+  }
+  async getPayerReceipt(invoiceId, preimage) {
+    return this.request("GET", `/api/invoice/${invoiceId}/receipt`, void 0, {
+      preimage
+    });
+  }
+  async getSettings() {
+    return this.request("GET", "/api/public-settings");
+  }
+  async waitForSettlement(invoiceId, options) {
+    const interval = options?.pollInterval ?? 2e3;
+    const timeout = options?.timeout ?? 3e5;
+    const start = Date.now();
+    while (Date.now() - start < timeout) {
+      const status = await this.getUnlockStatus([invoiceId]);
+      const entry = status.statuses?.[String(invoiceId)];
+      if (entry?.unlocked) {
+        return entry;
+      }
+      if (entry?.status === "failed" || entry?.status === "expired") {
+        return entry;
+      }
+      await new Promise((r) => setTimeout(r, interval));
+    }
+    throw new HypawaveAPIError(408, {
+      error: "settlement_timeout",
+      message: `Settlement not confirmed within ${timeout}ms`
+    });
+  }
+  async payAndConfirm(params) {
+    const capability = params.wallet.capabilities?.returnsPreimage;
+    if (capability === false || capability === void 0) {
+      throw new HypawaveAPIError(400, {
+        error: "wallet_no_preimage_support",
+        message: "This wallet does not support returning the preimage. Hypawave requires the preimage for settlement confirmation. Use a supported adapter (NWC, LND, CLN, Alby, LNbits) from @hypawave/lightning-adapters."
+      });
+    }
+    if (capability === "conditional" && !params.allowConditionalPreimage) {
+      throw new HypawaveAPIError(400, {
+        error: "wallet_conditional_preimage",
+        message: "This wallet conditionally supports preimage return (depends on the backing node). Set allowConditionalPreimage: true to proceed at your own risk. If the preimage is not returned after payment, files will not unlock."
+      });
+    }
+    const { pr: bolt11, terms_hash } = await this.getBolt11(params.accessToken);
+    const payResult = await params.wallet.payInvoice(bolt11);
+    if (!payResult.preimage || !/^[0-9a-f]{64}$/i.test(payResult.preimage)) {
+      throw new HypawaveAPIError(400, {
+        error: "wallet_did_not_return_preimage",
+        message: "Wallet did not return a valid preimage. Hypawave requires a 64-char hex preimage for settlement confirmation."
+      });
+    }
+    const computedHash = await sha256hex(payResult.preimage);
+    if (payResult.payment_hash && computedHash.toLowerCase() !== payResult.payment_hash.toLowerCase()) {
+      throw new HypawaveAPIError(400, {
+        error: "preimage_hash_mismatch",
+        message: `Client-side verification failed: SHA256(preimage) does not match payment_hash. Expected ${payResult.payment_hash}, got ${computedHash}.`
+      });
+    }
+    const paymentHash = payResult.payment_hash || computedHash;
+    const confirmation = await this.confirmPayment(params.invoiceId, {
+      payment_hash: paymentHash,
+      preimage: payResult.preimage,
+      terms_hash
+    });
+    return {
+      payment_hash: paymentHash,
+      preimage: payResult.preimage,
+      terms_hash,
+      fees_paid_msat: payResult.fees_paid_msat,
+      confirmation
+    };
+  }
+};
+export {
+  Hypawave,
+  HypawaveAPIError
+};

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@hypawave/sdk",
+  "version": "0.1.0",
+  "description": "TypeScript SDK for Lightning settlement, preimage proof, and execution unlocks for AI agents.",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts --clean",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "hypawave",
+    "lightning",
+    "lightning-sdk",
+    "lightning-api",
+    "lightning-network",
+    "bitcoin",
+    "bitcoin-payments",
+    "settlement",
+    "payments",
+    "paywall",
+    "non-custodial",
+    "agent",
+    "agent-payments",
+    "ai-agents",
+    "ai",
+    "llm",
+    "api",
+    "sdk",
+    "preimage",
+    "preimage-proof",
+    "wallet",
+    "nwc",
+    "bolt11",
+    "lnurl",
+    "x402",
+    "l402",
+    "micropayments"
+  ],
+  "author": "hypawave",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hypawave/sdk.git"
+  },
+  "homepage": "https://hypawave.com/docs",
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}