@hypawave/sdk 0.2.0 → 0.2.2

package/README.md

@@ -1,6 +1,6 @@
 # @hypawave/sdk
 
-**Lightning SDK for AI Agent Payments — non-custodial Bitcoin settlement with preimage proof**
+**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)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/hypawave/sdk/blob/main/LICENSE)
@@ -10,13 +10,19 @@
 
 > ⚠️ **Hypawave has no token and will never issue one.** Any "HYPA," "WAVE," airdrop, or token offer claiming to be from Hypawave is a scam. Hypawave is non-custodial Bitcoin Lightning settlement — buyers pay creators directly in sats. The protocol fee is the only economic primitive.
 
-TypeScript SDK for settlement-triggered Lightning execution. Fetch creator-direct Lightning invoices, confirm preimage proof, and trigger deterministic unlocks.
+Hypawave is programmable settlement infrastructure for AI agents: a non-custodial Bitcoin Lightning protocol where verified payment unlocks API access, files, agent actions, and digital work.
+
+This TypeScript SDK lets developers create creator-direct Lightning invoices, deliver payment payloads to payer agents, verify preimage proof, and trigger deterministic unlocks.
 
 **Payment is the authorization — confirmed settlement unconditionally unlocks access.**
 
 ## Why Hypawave
 
-AI agents need to pay and get access without accounts, custody, or manual delivery. Hypawave turns Lightning settlement proof into deterministic execution — the same preimage that proves payment also unlocks the file, the API call, or the webhook.
+Hypawave lets developers charge for digital work with one primitive: verified Bitcoin Lightning settlement unlocks access.
+
+Use it when an API, file, webhook, inference job, automation, or agent action should only run after payment. The SDK creates creator-direct Lightning invoices, packages payment instructions for payer agents, verifies preimage proof after payment, and returns the preimage your app gates execution on.
+
+The important difference from a normal invoice flow is that payment proof and authorization are the same event. Once the payer submits a valid preimage, Hypawave can release encrypted files, return gated data, or trigger execution without manual reconciliation, payer accounts, or custody.
 
 This SDK covers **Path 2**: account-based agent flows. Accountless Paths 3a and 3b use raw HTTP via [llms.txt](https://hypawave.com/llms.txt) and the [OpenAPI spec](https://hypawave.com/.well-known/openapi.json). Requires programmable Lightning infrastructure (LND, CLN, Alby API, LNbits, NWC, etc.) that returns the preimage after payment.
 
@@ -47,19 +53,21 @@ npm install @hypawave/sdk
 
 ## Quick Start
 
+This example shows the full settlement loop in one script for clarity. In production, the creator/developer usually creates the invoice, then sends either `payment_url` to a browser payer or `getPaymentPayload()` to a payer agent.
+
 ```typescript
 import { Hypawave } from "@hypawave/sdk";
 
 const pp = new Hypawave({ apiKey: "sk_live_..." });
 
-// Create a payment request for a payer agent
+// Create a payment request
 const invoice = await pp.createInvoice({
   client_email: "alice@example.com",
   client_first_name: "Alice",
   client_last_name: "Smith",
   amount: 5.00,
   due_date: "2026-12-31",
-  payment_destination: "creator@getalby.com",
+  payment_destination: "creator@getalby.com", // optional; defaults to the API key owner's Lightning Address
 });
 
 console.log(invoice.invoice_id);   // Use for confirmation + key retrieval
@@ -169,6 +177,10 @@ const invoice = await pp.createInvoice({
 });
 ```
 
+`payment_destination` is optional — defaults to the API key owner's stored Lightning Address. Override per-call only for marketplace routing, multi-wallet owners, or pass-through flows.
+
+**Delivery primitives.** The response returns two ways to deliver the invoice. `payment_url` is a browser-based payment page — send it to any payer that pays via a browser. `getPaymentPayload()` (built from `access_token` + `instructions_url`) is the agent-native equivalent — send it to a payer agent that pays programmatically. Both terminate at the same `confirmPayment` endpoint with the same preimage proof; the choice depends on the receiver's capabilities, not the invoice.
+
 ### `getBolt11(accessToken)`
 
 Fetch the creator-issued Lightning bolt11 invoice for payment. The `access_token`
@@ -365,11 +377,10 @@ const settings = await pp.getSettings();
 Additional methods available — see types for full signatures, or [openapi.json](https://hypawave.com/.well-known/openapi.json) for the complete API reference.
 
 - `listInvoices(params?)` — list invoices with filters and pagination
-- `getPayerReceipt(invoiceId, accessToken)` — receipt fetch using a payer access token (no API key needed)
+- `getPayerReceipt(invoiceId, preimage)` — payer receipt fetch using the Lightning preimage as proof of payment (no API key needed)
 - `getUploadUrl(params)` — signed URL for encrypted file upload (creator side)
 - `storeFile(params)` — register an uploaded file against an invoice
 - `storeFileKey(params)` — register a file's encryption key against an invoice
-- `request(path, options)` — low-level escape hatch for direct API calls
 
 ## Error Handling
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hypawave/sdk",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "TypeScript SDK for Lightning settlement, preimage proof, and execution unlocks for AI agents.",
   "main": "dist/index.js",
   "module": "dist/index.mjs",