From 2c6e6c47526a5f25880d921ff6cd4782094346a5 Mon Sep 17 00:00:00 2001
From: Ayesh Almeida <ayesh9303@gmail.com>
Date: Wed, 19 Feb 2025 14:51:53 +0530
Subject: [PATCH] Update package spec

---
 docs/spec/spec.md | 31 +++++++++++++++++++++++++++++++
 1 file changed, 31 insertions(+)

diff --git a/docs/spec/spec.md b/docs/spec/spec.md
index 0193374d..dac08dbb 100644
--- a/docs/spec/spec.md
+++ b/docs/spec/spec.md
@@ -35,6 +35,7 @@ The conforming implementation of the specification is released and included in t
        * 2.2.2.7. [onUnsubscritpion](#2227-onunsubscritpion)
        * 2.2.2.8. [onUnsubscriptionValidation](#2228-onunsubscriptionvalidation)
        * 2.2.2.9. [onUnsubscriptionIntenVerified](#2229-onunsubscriptionintenverified)
+     * 2.2.3. [Controller](#223-controller)
    * 2.3. [Hub Client](#23-hub-client)
      * 2.3.1. [Initialization](#231-initialization)
      * 2.3.2. [Distribute Content](#232-distribute-content)
@@ -223,9 +224,11 @@ Apart from the listener level configurations a `hub` will require few additional
 #
 # + leaseSeconds - The period for which the subscription is expected to be active in the `hub`
 # + webHookConfig - HTTP client configurations for subscription/unsubscription intent verification
+# + autoVerifySubscription - Configuration to enable or disable automatic subscription verification
 public type ServiceConfiguration record {|
     int leaseSeconds?;
     ClientConfiguration webHookConfig?;
+    boolean autoVerifySubscription = false;
 |};
 ```
 
@@ -375,6 +378,34 @@ This is due to the limited information in the WebSub specification on the relati
 In the event of a bad request from the `publisher` or the `subscriber`, the WebSubHub dispatcher will automatically send 
 back the appropriate response to the client.
 
+#### 2.2.3. Controller
+
+When `autoVerifySubscription` is enabled in the `websubhub:ServiceConfig` annotation, the `websubhub:Controller` can be used to mark a 
+subscription or unsubscription as verified. This class is initialized exclusively within the WebSubHub framework and provides the 
+following API.
+
+```ballerina
+type Controller object {
+
+    # Marks a particular subscription as verified.
+    #
+    # + subscription - The `websubhub:Subscription` or `websubhub:Unsubscription` message
+    # + return - A `websubhub:Error` if the `websubhub:Service` has not enabled subscription auto-verification, 
+    #           or else nil
+    public isolated function markAsVerified(Subscription|Unsubscription subscription) returns Error?;
+
+    # Checks whether a particular subscription has been marked as verified. Please note that this 
+    # is an internal API which is used within the WebSubHub dispatcher to identify whether 
+    # to skip the subscrition intent verification for the subscription or unsubscription.
+    # 
+    # + subscription - The `websubhub:Subscription` or `websubhub:Unsubscription` message
+    # + return - A `true` if the subscrition/unsubscription has been marked as verified or else `false`
+    isolated function skipSubscriptionVerification(Subscription|Unsubscription subscription) returns boolean;
+};
+```
+
+> Note: The `websubhub:Controller` will be available only as an optional parameter in the `onSubscription` and `onUnsubscription` remote methods of the `websubhub:Service`.
+
 ### 2.3. Hub Client
 
 In accordance with the [WebSub specification](https://www.w3.org/TR/websub/#content-distribution), `WebSubHub` package