Merge pull request #43 from 398ja/codex/document-request-parameters-and-methods

Add webhook and client reference docs

Author: tcheeric

docs/reference/README.md

@@ -0,0 +1,6 @@
+# Reference
+
+- [REST API](rest-api.md)
+- [Configuration](configuration.md)
+- [Webhook Handler](webhook.md)
+- [Java Client](client.md)

docs/reference/client.md

@@ -0,0 +1,27 @@
+# Java Client
+
+The `cashu-gateway-client` module offers REST clients for interacting with the service.
+
+## Common Methods
+
+Available on all client classes.
+
+| Method | Inputs | Response |
+|--------|--------|----------|
+| `get(Long id)` | Numeric identifier | Returns the entity with the given id or `null`. |
+| `getByEntityId(String entityId)` | External id (`paymentId` or `quoteId`) | Returns the matching entity or `null`. |
+| `create(T entity)` | Entity instance | Persists the entity and returns the created object. |
+| `delete(Long id)` | Numeric identifier | Deletes the entity, response is empty. |
+
+## PaymentClient
+
+| Method | Inputs | Response | Description |
+|--------|--------|----------|-------------|
+| `getByQuoteId(String quoteId)` | Quote id | `GatewayPayment` linked to the quote. |
+| `updatePayment(GatewayPayment payment)` | Updated payment | `GatewayPayment` after update. |
+
+## QuoteClient
+
+| Method | Inputs | Response | Description |
+|--------|--------|----------|-------------|
+| `getByInvoiceId(String invoiceId)` | Lightning invoice id | Matching `GatewayQuote`. |

docs/reference/configuration.md

@@ -59,4 +59,4 @@ This document lists configuration properties and environment variables available
 
 | Property | Default | Description |
 | --- | --- | --- |
-| `A1b2C3d4.wid` | `phoenixd` | Webhook identifier expected by validator. |
+| `A1b2C3d4.wid` | `phoenixd` | Webhook identifier expected by validator. |

docs/reference/rest-api.md

@@ -0,0 +1,19 @@
+# REST API
+
+The REST service exposes endpoints for managing quotes and payments. Base URL defaults to `http://localhost:8080`.
+
+## Quote Endpoints
+
+- `GET /quote` – list quotes
+- `POST /quote` – create a quote
+- `GET /quote/{id}` – fetch a quote by numeric id
+- `GET /quote/search/findByQuoteId?quoteId=...` – fetch by external quote id
+- `GET /quote/search/findByInvoiceId?invoiceId=...` – fetch by Lightning invoice id
+
+## Payment Endpoints
+
+- `GET /payment` – list payments
+- `POST /payment` – create a payment
+- `GET /payment/{id}` – fetch a payment by numeric id
+- `GET /payment/search/findByPaymentId?paymentId=...`
+- `GET /payment/search/findByQuoteId?quoteId=...`

docs/reference/webhook.md

@@ -0,0 +1,35 @@
+# Webhook Handler
+
+`cashu-gateway-webhook` exposes a servlet at `/webhook` for processing payment notifications.
+
+## Request Parameters
+
+| Name | Required | Description |
+|------|----------|-------------|
+| `wid` | Yes | Identifies the webhook source (`phoenixd` or `dummy`). If absent in the request, the system property `wid` is used. |
+| `type` | Yes (phoenixd) | Expected value `payment_received`. |
+| `amountSat` | Yes (phoenixd) | Payment amount in satoshis. |
+| `paymentHash` | Yes (phoenixd) | Lightning payment hash. |
+| `externalId` | Yes (phoenixd) | Lightning invoice identifier used to look up the quote. |
+
+The webhook expects parameters in an `application/x-www-form-urlencoded` payload.
+
+### Example
+
+```
+POST /webhook
+wid=phoenixd&type=payment_received&amountSat=1000&paymentHash=<hash>&externalId=<invoice>
+```
+
+## Validation Rules
+
+Requests with `wid=phoenixd` are validated as follows:
+
+1. Retrieve the quote by `externalId` and ensure it exists and has direction `RECEIVE`.
+2. Load the payment linked to the quote.
+3. Confirm `paymentHash` and `amountSat` match the stored payment.
+4. Verify the payment state is `PAID` and the webhook `type` is `payment_received`.
+
+If validation succeeds, the payment is marked `CONFIRMED` and a `201 Created` response is returned. Any failure results in `401 Unauthorized`.
+
+The `dummy` webhook id is provided for testing and creates a placeholder payment without validation.