graph: don't expose Common module

ms-graph-api/README.md

@@ -9,9 +9,9 @@ Haskell client bindings to the [Microsoft Graph API v1.0](https://learn.microsof
 
 ## Introduction
 
-This library provides both the client interface (under the `MSGraphAPI` namespace) as well as helpers to integrate with Microsoft infrastructure, e.g. using ActiveDirectory as an OAuth2 identity provider.
+This library provides both client interface to the MS Grapi API (under the `MSGraphAPI` namespace).
 
-With the provided auth functions (see `Network.OAuth2.Session`) you can easily implement OAuth2 for your application, and the resulting token store is thread-safe and automatically renews before expiring.
+Authentication can be implemented with the `ms-auth` library.
 
 ## Status
 
@@ -26,6 +26,7 @@ Some breaking changes might also be introduced as the library matures.
 
 We adhere to the [Package Versioning Policy](https://pvp.haskell.org/): major breaking changes or API refactors are signaled by increasing the first major version number (i.e. 0.0.0.0 -> 1.0.0.0 ) whereas less significant ones are indicated by increasing the second one (0.0.0.0 -> 0.1.0.0)
 
+Significant changes in the SDK will be documented in the respective CHANGELOG.
 
 ## Copyright
 

ms-graph-api/ms-graph-api.cabal

@@ -1,8 +1,8 @@
 name:                ms-graph-api
-version:             0.7.0.0
+version:             0.8.0.0
 synopsis:            Microsoft Graph API
 description:         Bindings to the Microsoft Graph API
-homepage:            https://github.com/unfoldml/ms-api
+homepage:            https://github.com/unfoldml/ms-graph-api
 license:             BSD3
 license-file:        LICENSE
 author:              Marco Zocca
@@ -24,8 +24,7 @@ library
                        MSGraphAPI.Users.Group
                        MSGraphAPI.Drive
                        MSGraphAPI.Files.DriveItem
-                       MSGraphAPI.Internal.Common
-  other-modules:       MSGraphAPI.Auth
+  other-modules:       MSGraphAPI.Internal.Common
   build-depends:       base >= 4.7 && < 5
                      , aeson
                      , bytestring

ms-graph-api/src/MSGraphAPI/ChangeNotifications/Subscription.hs

@@ -1,3 +1,8 @@
+-- | Subscription to change notifications through webhooks
+--
+-- see <https://learn.microsoft.com/en-us/graph/webhooks#supported-resources> for a list of resources that can produce change notifications
+--
+-- see <https://learn.microsoft.com/en-us/graph/change-notifications-delivery-webhooks?tabs=http> for protocol details
 module MSGraphAPI.ChangeNotifications.Subscription where
 
 import Data.List.NonEmpty (NonEmpty)
@@ -14,11 +19,31 @@ import Network.HTTP.Req (Req)
 import Data.Text (Text, pack, unpack)
 -- time
 import Data.Time (LocalTime)
+-- import Data.UUID.Types (UUID)
 
 import qualified MSGraphAPI.Internal.Common as MSG (Collection(..), get, post, aesonOptions)
 import MSGraphAPI.Files.DriveItem (DriveItem)
 
--- | Creating a subscription requires read scope to the resource. For example, to get change notifications on messages, your app needs the Mail.Read permission.
+-- | Represents the notification sent to the subscriber. https://learn.microsoft.com/en-us/graph/api/resources/changenotification?view=graph-rest-1.0
+--
+-- 
+data ChangeNotification a = ChangeNotification {
+  cnChangeType :: ChangeType
+  , cnClientState :: Text
+  , cnId :: Text
+  , cnResource :: Text
+  , cnResourceData :: Maybe a
+  , cnSubscriptionId :: Text
+  , cnTenantId :: Text
+                                             } deriving (Eq, Show, Generic)
+instance A.FromJSON a => A.FromJSON (ChangeNotification a) where
+  parseJSON = A.genericParseJSON (MSG.aesonOptions "cn")
+
+-- | Create a subscription https://learn.microsoft.com/en-us/graph/api/subscription-post-subscriptions?view=graph-rest-1.0&tabs=http
+--
+-- @ POST https:\/\/graph.microsoft.com\/v1.0\/subscriptions@
+--
+-- Creating a subscription requires read scope to the resource. For example, to get change notifications on messages, your app needs the @Mail.Read@ permission.
 createSubscription :: (A.FromJSON b) => Subscription -> AccessToken -> Req b
 createSubscription = MSG.post ["subscriptions"] mempty
 
@@ -31,7 +56,7 @@ data Subscription = Subscription {
   , cnsClientState :: Text
   , cnsExpirationDateTime :: LocalTime
   , cnsNotificationUrl :: Text -- ^ The URL of the endpoint that will receive the change notifications. This URL must make use of the HTTPS protocol. Any query string parameter included in the notificationUrl property will be included in the HTTP POST request when Microsoft Graph sends the change notifications.
-  , cnsResource :: Text -- ^ Specifies the resource that will be monitored for changes. Do not include the base URL (https://graph.microsoft.com/v1.0/)
+  , cnsResource :: Text -- ^ Specifies the resource that will be monitored for changes. Do not include the base URL (@https:\/\/graph.microsoft.com\/v1.0\/@)
   , cnsLatestSupportedTLSVersion :: LatestTLSVer
                    } deriving (Eq, Show, Generic)
 instance A.FromJSON Subscription where