fixup: LSPS5 events - Improve type safety and documentation

- Replaces raw error code/message pairs with a structured LSPS5Error type
- Changes String timestamp fields to use the proper LSPSDateTime type
- Improves documentation with references to MAX_APP_NAME_LENGTH constant

Author: martinsaposnic

lightning-liquidity/src/lsps5/event.rs

@@ -9,15 +9,16 @@
 
 //! Events generated by the LSPS5 service and client
 
+use crate::lsps0::ser::LSPSDateTime;
 use crate::lsps0::ser::LSPSRequestId;
 use alloc::string::String;
 use alloc::vec::Vec;
 use bitcoin::secp256k1::PublicKey;
 
 use super::msgs::LSPS5AppName;
+use super::msgs::LSPS5Error;
 use super::msgs::LSPS5WebhookUrl;
 use super::msgs::WebhookNotification;
-
 /// An event which an bLIP-55 / LSPS5 server should take some action in response to.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub enum LSPS5ServiceEvent {
@@ -26,101 +27,119 @@ pub enum LSPS5ServiceEvent {
 	/// This event occurs when a client successfully registers a webhook via `lsps5.set_webhook`.
 	/// You should store this information to be able to contact the client when they are offline.
 	WebhookRegistered {
-		/// Client node ID that registered the webhook
+		/// Client node ID that registered the webhook.
 		counterparty_node_id: PublicKey,
-		/// App name provided by the client (up to 64 bytes in UTF-8 format)
+		/// App name provided by the client.
+		///
+		/// This app name is used to identify the webhook registration.
+		///
+		/// **Note**: Ensure the app name is valid and its length does not exceed [`MAX_APP_NAME_LENGTH`].
+		///
+		/// [`MAX_APP_NAME_LENGTH`]: super::msgs::MAX_APP_NAME_LENGTH
 		app_name: LSPS5AppName,
-		/// Webhook URL (HTTPS) that should be contacted to notify the client (up to 1024 ASCII characters)
+		/// Webhook URL (HTTPS) to be contacted for notifying the client.
+		///
+		/// This URL is used by the LSP to send notifications.
+		///
+		/// **Note**: Ensure the URL is valid and its length does not exceed [`MAX_WEBHOOK_URL_LENGTH`].
+		/// Also ensure that the URL points to a public host.
+		///
+		/// [`MAX_WEBHOOK_URL_LENGTH`]: super::msgs::MAX_WEBHOOK_URL_LENGTH
 		url: LSPS5WebhookUrl,
-		/// The identifier of the issued bLIP-55 / LSPS5 webhook registration request
+		/// The identifier of the issued bLIP-55 / LSPS5 webhook registration request.
 		///
 		/// This can be used to track which request this event corresponds to.
 		request_id: LSPSRequestId,
-		/// Whether this was a new registration or an update to existing one with no changes
-		/// If false, a notification should be sent to the registered webhook
+		/// Whether this was a new registration or an update to existing one with no changes.
+		/// If false, a notification should be sent to the registered webhook.
 		no_change: bool,
 	},
 
-	/// Webhooks were listed for a client
+	/// Webhooks were listed for a client.
 	///
 	/// This event occurs when a client requests their registered webhooks via `lsps5.list_webhooks`.
 	WebhooksListed {
-		/// Client node ID that requested their webhooks
+		/// Client node ID that requested their webhooks.
 		counterparty_node_id: PublicKey,
-		/// App names with registered webhooks for this client
+		/// App names with registered webhooks for this client.
 		app_names: Vec<LSPS5AppName>,
-		/// The identifier of the issued bLIP-55 / LSPS5 webhook listing request
+		/// The identifier of the issued bLIP-55 / LSPS5 webhook listing request.
 		///
 		/// This can be used to track which request this event corresponds to.
 		request_id: LSPSRequestId,
-		/// Maximum number of webhooks allowed by LSP per client
+		/// Maximum number of webhooks allowed by LSP per client.
 		max_webhooks: u32,
 	},
 
-	/// A webhook was removed by a client
+	/// A webhook was removed by a client.
 	///
 	/// This event occurs when a client successfully removes a webhook via `lsps5.remove_webhook`.
 	WebhookRemoved {
-		/// Client node ID that removed the webhook
+		/// Client node ID that removed the webhook.
 		counterparty_node_id: PublicKey,
-		/// App name that was removed
+		/// App name that was removed.
 		app_name: LSPS5AppName,
-		/// The identifier of the issued bLIP-55 / LSPS5 webhook removal request
+		/// The identifier of the issued bLIP-55 / LSPS5 webhook removal request.
 		///
 		/// This can be used to track which request this event corresponds to.
 		request_id: LSPSRequestId,
 	},
 
-	/// A notification needs to be sent to a client's webhook
+	/// A notification needs to be sent to a client's webhook.
 	///
 	/// This event occurs when the LSP needs to send a notification to a client's webhook.
 	/// When this event is received, the LSP should:
-	/// 1. Serialize the notification to JSON
-	/// 2. Make an HTTP POST request to the provided URL with the given headers and the serialized notification
+	/// 1. Serialize the notification to JSON.
+	/// 2. Make an HTTP POST request to the provided
+	/// URL with the given headers and the serialized notification.
 	///
 	/// When the client receives this notification, they will process it and generate a
 	/// `WebhookNotificationReceived` event on their side. The client will validate the
 	/// signature using the LSP's node ID to ensure the notification is authentic.
 	SendWebhookNotifications {
-		/// Client node ID to be notified
+		/// Client node ID to be notified.
 		counterparty_node_id: PublicKey,
-		/// App name to be notified
+		/// App name to be notified.
 		app_name: LSPS5AppName,
-		/// URL that to be contacted
+		/// URL that to be contacted.
 		url: LSPS5WebhookUrl,
-		/// Notification method with its parameters
+		/// Notification method with its parameters.
 		notification: WebhookNotification,
-		/// ISO8601 timestamp of the notification (YYYY-MM-DDThh:mm:ss.uuuZ format)
-		timestamp: String,
-		/// Signature of the notification using the LSP's node ID
+		///  Timestamp of the notification.
+		timestamp: LSPSDateTime,
+		/// Signature of the notification using the LSP's node ID.
 		signature: String,
-		/// Headers to be included in the HTTP POST request
+		/// Headers to be included in the HTTP POST request.
+		///
+		/// Content-Type (application/json).
+		/// x-lsps5-timestamp (timestamp in RFC3339 (YYYY-MM-DDThh:mm:ss.uuuZ) format).
+		/// x-lsps5-signature (signature of the notification using the LSP's node ID).
 		headers: Vec<(String, String)>,
 	},
 }
 
 /// An event which an LSPS5 client should take some action in response to.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub enum LSPS5ClientEvent {
-	/// A webhook was successfully registered with the LSP
+	/// A webhook was successfully registered with the LSP.
 	///
 	/// This event is triggered when the LSP confirms successful registration
 	/// of a webhook via `lsps5.set_webhook`.
 	WebhookRegistered {
-		/// The node id of the LSP that confirmed the registration
+		/// The node id of the LSP that confirmed the registration.
 		counterparty_node_id: PublicKey,
-		/// Current number of webhooks registered for this client
+		/// Current number of webhooks registered for this client.
 		num_webhooks: u32,
-		/// Maximum number of webhooks allowed by LSP
+		/// Maximum number of webhooks allowed by LSP.
 		max_webhooks: u32,
-		/// Whether this was an unchanged registration (same app_name and URL)
-		/// If true, the LSP didn't send a webhook notification for this registration
+		/// Whether this was an unchanged registration (same app_name and URL).
+		/// If true, the LSP didn't send a webhook notification for this registration.
 		no_change: bool,
-		/// The app name that was registered (up to 64 bytes in UTF-8 format)
+		/// The app name that was registered.
 		app_name: LSPS5AppName,
-		/// The webhook URL that was registered (HTTPS protocol)
+		/// The webhook URL that was registered.
 		url: LSPS5WebhookUrl,
-		/// The identifier of the issued bLIP-55 / LSPS5 webhook registration request
+		/// The identifier of the issued bLIP-55 / LSPS5 webhook registration request.
 		///
 		/// This can be used to track which request this event corresponds to.
 		request_id: LSPSRequestId,
@@ -132,102 +151,95 @@ pub enum LSPS5ClientEvent {
 	/// via `lsps5.set_webhook`. This can happen if the app_name or URL is too long,
 	/// the URL uses an unsupported protocol, or the maximum number of webhooks is reached.
 	WebhookRegistrationFailed {
-		/// The node id of the LSP that rejected the registration
+		/// The node id of the LSP that rejected the registration.
 		counterparty_node_id: PublicKey,
-		/// Error code from the LSP (500: too_long, 501: url_parse_error,
-		/// 502: unsupported_protocol, 503: too_many_webhooks)
-		error_code: i32,
-		/// Error message from the LSP
-		error_message: String,
-		/// The app name that was attempted
+		/// Error from the LSP.
+		error: LSPS5Error,
+		/// The app name that was attempted.
 		app_name: LSPS5AppName,
-		/// The webhook URL that was attempted
+		/// The webhook URL that was attempted.
 		url: LSPS5WebhookUrl,
-		/// The identifier of the issued bLIP-55 / LSPS5 webhook registration request
+		/// The identifier of the issued bLIP-55 / LSPS5 webhook registration request.
 		///
 		/// This can be used to track which request this event corresponds to.
 		request_id: LSPSRequestId,
 	},
 
-	/// The list of registered webhooks was successfully retrieved
+	/// The list of registered webhooks was successfully retrieved.
 	///
 	/// This event is triggered when the LSP responds to a `lsps5.list_webhooks` request.
 	WebhooksListed {
-		/// The node id of the LSP that provided the list
+		/// The node id of the LSP that provided the list.
 		counterparty_node_id: PublicKey,
-		/// List of app names with registered webhooks
+		/// List of app names with registered webhooks.
 		app_names: Vec<LSPS5AppName>,
-		/// Maximum number of webhooks allowed by LSP
+		/// Maximum number of webhooks allowed by LSP.
 		max_webhooks: u32,
-		/// The identifier of the issued bLIP-55 / LSPS5 list webhooks request
+		/// The identifier of the issued bLIP-55 / LSPS5 list webhooks request.
 		///
 		/// This can be used to track which request this event corresponds to.
 		request_id: LSPSRequestId,
 	},
 
-	/// The attempt to list webhooks failed
+	/// The attempt to list webhooks failed.
 	///
 	/// This event is triggered when the LSP rejects a `lsps5.list_webhooks` request.
 	WebhooksListFailed {
-		/// The node id of the LSP that rejected the request
+		/// The node id of the LSP that rejected the request.
 		counterparty_node_id: PublicKey,
-		/// Error code from the LSP
-		error_code: i32,
-		/// Error message from the LSP
-		error_message: String,
-		/// The identifier of the issued bLIP-55 / LSPS5 list webhooks request
+		/// Error from the LSP.
+		error: LSPS5Error,
+		/// The identifier of the issued bLIP-55 / LSPS5 list webhooks request.
 		///
 		/// This can be used to track which request this event corresponds to.
 		request_id: LSPSRequestId,
 	},
 
-	/// A webhook was successfully removed
+	/// A webhook was successfully removed.
 	///
 	/// This event is triggered when the LSP confirms successful removal
 	/// of a webhook via `lsps5.remove_webhook`.
 	WebhookRemoved {
-		/// The node id of the LSP that confirmed the removal
+		/// The node id of the LSP that confirmed the removal.
 		counterparty_node_id: PublicKey,
-		/// The app name that was removed
+		/// The app name that was removed.
 		app_name: LSPS5AppName,
-		/// The identifier of the issued bLIP-55 / LSPS5 remove webhook request
+		/// The identifier of the issued bLIP-55 / LSPS5 remove webhook request.
 		///
 		/// This can be used to track which request this event corresponds to.
 		request_id: LSPSRequestId,
 	},
 
-	/// A webhook removal attempt failed
+	/// A webhook removal attempt failed.
 	///
 	/// This event is triggered when the LSP rejects a webhook removal
 	/// via `lsps5.remove_webhook`. The most common error is app_name_not_found (1010).
 	WebhookRemovalFailed {
-		/// The node id of the LSP that rejected the removal
+		/// The node id of the LSP that rejected the removal.
 		counterparty_node_id: PublicKey,
-		/// Error code from the LSP (1010: app_name_not_found)
-		error_code: i32,
-		/// Error message from the LSP
-		error_message: String,
-		/// The app name that was attempted to be removed
+		/// Error from the LSP.
+		error: LSPS5Error,
+		/// The app name that was attempted to be removed.
 		app_name: LSPS5AppName,
-		/// The identifier of the issued bLIP-55 / LSPS5 remove webhook request
+		/// The identifier of the issued bLIP-55 / LSPS5 remove webhook request.
 		///
 		/// This can be used to track which request this event corresponds to.
 		request_id: LSPSRequestId,
 	},
 
-	/// A webhook notification was received from the LSP
+	/// A webhook notification was received from the LSP.
 	///
 	/// This event is triggered when the client receives a webhook notification
 	/// from the LSP. This can happen for various reasons such as incoming payment,
 	/// expiring HTLCs, liquidity management requests, or incoming onion messages.
 	WebhookNotificationReceived {
-		/// LSP node ID that sent the notification
+		/// LSP node ID that sent the notification.
 		counterparty_node_id: PublicKey,
-		/// The notification with its method and parameters
+		/// The notification with its method and parameters.
 		notification: WebhookNotification,
-		/// Timestamp of the notification in ISO8601 format (YYYY-MM-DDThh:mm:ss.uuuZ)
-		timestamp: String,
-		/// Whether the LSP's signature was successfully verified
+		/// Timestamp of the notification.
+		timestamp: LSPSDateTime,
+		/// Whether the LSP's signature was successfully verified.
 		signature_valid: bool,
 	},
 }