Merge pull request #171 from PortalTechnologiesInc/wheatley/rest-api-webhooks

refactor(portal-rest): REST + polling + webhooks API

Author: denmeh

.gitignore

@@ -9,4 +9,5 @@ node_modules
 
 react-native/portal-app-lib-*.tgz
 
-result
+result
+examples/.env

CHANGELOG.md

@@ -12,6 +12,37 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
 ---
 
+### [0.4.0] - 2026-03-17
+
+#### Changed
+- **WebSocket → REST**: All endpoints are now standard HTTP (POST/GET/PUT/DELETE); WebSocket API removed
+- Async operations (key handshake, payments, invoices, cashu) now return `stream_id` immediately; events are delivered via webhooks or polling (`GET /events/:stream_id`)
+- `GET /version` response now wrapped in standard `ApiResponse` envelope
+- Profile is now set via `[profile]` config / env vars at startup; `SetProfile` command removed
+- `FAKE_PAYMENTS` feature gated behind `#[cfg(debug_assertions)]`
+- `/.well-known/nostr.json` is now a public endpoint (no auth required) for NIP-05 verification
+
+#### Added
+- **Webhook delivery**: HMAC-SHA256 signed POST (`X-Portal-Signature` header) to configured URL on every stream event
+- **SQLite event persistence**: Events stored with WAL mode; startup recovery for in-flight `single_payment` streams
+- `GET /info`: New authenticated endpoint returning server public key
+- **TypeScript SDK**: `autoPollingIntervalMs` config option starts a background scheduler; `poll(op)` now typed — takes `AsyncOperation<T>`, returns `T`; `destroy()` stops the auto-poller; `webhookHandler()` for HMAC-verified webhook processing
+- **Java SDK** (`portal-java-sdk`): Full rewrite from WebSocket to REST; `PortalClient` with `PortalClientConfig` supporting manual polling, auto-polling, and webhooks; all async methods return typed `AsyncOperation<T>`
+- **OpenAPI spec**: `openapi.yaml` with all endpoints, request/response schemas, and `StreamIdResponse` for async operations
+- **Documentation**: Full mdBook docs with HTTP/curl tabs on every page, REST API guide, interactive OpenAPI viewer (Redoc), updated environment variables reference
+- **Examples**: Runnable Node.js examples (`auth.js`, `single-payment.js`, `profile.js`, `error-handling.js`) with `.env` support
+- **Security**: Constant-time Bearer token comparison (`subtle::ConstantTimeEq`); constant-time webhook signature verification (`timingSafeEqual`)
+- **Performance**: Shared `reqwest::Client` in `EventStore` for webhook delivery (no per-event allocation)
+
+#### Fixed
+- TypeScript SDK: `requestSinglePayment`, `requestPaymentRaw`, `requestRecurringPayment` now return correctly typed `AsyncOperation<T>` (previously returned raw `StreamEvent`)
+
+#### Removed
+- WebSocket API (`/ws` endpoint)
+- `SetProfile` / `ListenClosedRecurringPayment` commands
+
+---
+
 ### [0.3.0] - 2026-02-26
 
 #### Changed

Cargo.lock

@@ -38,6 +38,7 @@ bitcoin = "0.32.5"
 jwt-compact = { version = "0.9.0-beta.1", features = ["es256k"] }
 secp256k1 = "0.29"
 sha2 = "0.10"
+hmac = "0.12"
 
 # -----------------------------------------------------------------------------
 # Error handling & logging
@@ -87,6 +88,7 @@ uniffi = "0.29.1"
 # -----------------------------------------------------------------------------
 config = { version = "0.15.19", features = ["toml"] }
 dashmap = "6.1.0"
+rusqlite = { version = "0.31", features = ["bundled"] }
 dirs = "6.0.0"
 
 # -----------------------------------------------------------------------------

Cargo.toml

@@ -7,14 +7,14 @@
 
 **Portal is the identity and payment layer for Bitcoin-native applications — no accounts, no KYC, no payment processor.**
 
-Users interact through the Portal mobile app using their Nostr identity. You run a single Docker container and talk to it with our SDK.
+Users interact through the Portal mobile app using their Nostr identity. You run a single Docker container and call its REST API from any language.
 
 ---
 
 ## How it works
 
 ```
-Your backend  ←—WebSocket—→  sdk-daemon  ←—Nostr relays—→  Portal app (user's phone)
+Your backend  ←—REST API—→  sdk-daemon  ←—Nostr relays—→  Portal app (user's phone)
 ```
 
 1. Your backend asks sdk-daemon for a handshake URL → show it as a QR code
@@ -31,46 +31,26 @@ Your backend  ←—WebSocket—→  sdk-daemon  ←—Nostr relays—→  Porta
 docker run -d -p 3000:3000 \
   -e PORTAL__AUTH__AUTH_TOKEN=your-secret-token \
   -e PORTAL__NOSTR__PRIVATE_KEY=your-nostr-private-key-hex \
-  getportal/sdk-daemon:0.3.0
+  getportal/sdk-daemon:0.4.0
 ```
 
-**2. Install the SDK**
+**2. Call the REST API**
 
 ```bash
-npm install portal-sdk          # TypeScript / JavaScript
-```
-
-```groovy
-// Java (Gradle) — via JitPack
-implementation 'com.github.PortalTechnologiesInc:java-sdk:0.3.0'
-```
-
-**3. Connect and authenticate a user**
+# Get a handshake URL — show it to the user as a QR code
+curl -s -X POST http://localhost:3000/key-handshake \
+  -H "Authorization: Bearer your-secret-token" \
+  -H "Content-Type: application/json" \
+  -d '{}' | jq .
 
-```typescript
-import { PortalSDK } from 'portal-sdk';
+# → { "stream_id": "abc123", "url": "nostr+walletconnect://..." }
 
-const client = new PortalSDK({ serverUrl: 'ws://localhost:3000/ws' });
-await client.connect();
-await client.authenticate('your-secret-token');
-
-const url = await client.newKeyHandshakeUrl((userKey) => {
-  console.log('User authenticated:', userKey);
-});
-// Show `url` as a QR code to the user
+# Poll for the user's public key (repeat until events arrive)
+curl -s "http://localhost:3000/events/abc123?after=0" \
+  -H "Authorization: Bearer your-secret-token" | jq .
 ```
 
----
-
-## SDK versions
-
-| SDK | Version | Install |
-|-----|---------|---------|
-| TypeScript / JavaScript | `0.3.0` | `npm install portal-sdk` |
-| Java | `0.3.0` | [JitPack](https://jitpack.io/#PortalTechnologiesInc/java-sdk) |
-| Docker image | `0.3.0` | `docker pull getportal/sdk-daemon:0.3.0` |
-
-The SDK `major.minor` version must match the daemon. Patch versions are independent. See [Versioning & Compatibility](https://portaltechnologiesinc.github.io/lib/getting-started/versioning.html).
+Any language works — Python, Go, Ruby, PHP, Java, TypeScript. No SDK required.
 
 ---
 
@@ -84,11 +64,30 @@ The SDK `major.minor` version must match the daemon. Patch versions are independ
 
 ---
 
+## Documentation
+
+Full docs at **[portaltechnologiesinc.github.io/lib](https://portaltechnologiesinc.github.io/lib/)** — REST API reference, curl examples, guides for authentication, payments, Cashu, JWT, Docker deployment, and more.
+
+---
+
+## Official SDKs
+
+For JavaScript/TypeScript and Java, typed SDKs are available. They wrap the same REST API with auto-polling, webhook handling, and typed responses.
+
+| SDK | Version | Install |
+|-----|---------|---------|
+| TypeScript / JavaScript | `0.4.0` | `npm install portal-sdk` |
+| Java | `0.4.0` | [JitPack](https://jitpack.io/#PortalTechnologiesInc/java-sdk) |
+
+The SDK `major.minor` version must match the daemon. See [Versioning & Compatibility](https://portaltechnologiesinc.github.io/lib/getting-started/versioning.html).
+
+---
+
 ## This repository
 
 | Package | Description |
 |---------|-------------|
-| `portal-rest` | SDK Daemon — HTTP + WebSocket API server |
+| `portal-rest` | SDK Daemon — REST API server |
 | `portal` | Core Nostr protocol and conversation logic |
 | `portal-app` | App runtime and wallet integration |
 | `portal-wallet` | Wallet backends (NWC, Breez) |
@@ -98,10 +97,4 @@ The SDK `major.minor` version must match the daemon. Patch versions are independ
 
 ---
 
-## Documentation
-
-Full docs at **[portaltechnologiesinc.github.io/lib](https://portaltechnologiesinc.github.io/lib/)** — guides for authentication, payments, Cashu, JWT, relay setup, Docker deployment, and more.
-
----
-
 **License:** MIT · [Java SDK](https://github.com/PortalTechnologiesInc/java-sdk) · [Demo](https://github.com/PortalTechnologiesInc/portal-demo)