-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Library and command-line utility for accessing Google services and APIs.
--   
@package handa-gdata
@version 0.7


-- | Helper functions for accessing Google APIs.
module Network.Google

-- | OAuth 2.0 access token.
type AccessToken = ByteString

-- | Convert a string to an access token.
toAccessToken :: String -> AccessToken

-- | Google API project ID, see
--   <a>https://code.google.com/apis/console</a>.
type ProjectId = String

-- | Append a body to a request.
appendBody :: ByteString -> Request -> Request

-- | Append headers to a request.
appendHeaders :: [(String, String)] -> Request -> Request

-- | Append a query to a request.
appendQuery :: [(String, String)] -> Request -> Request
doManagedRequest :: DoRequest a => Manager -> Request -> IO a

-- | Perform a request.
doRequest :: DoRequest a => Request -> IO a

-- | Prepare a name/key for a header.
makeHeaderName :: String -> CI ByteString

-- | Construct a project-related Google API request.
makeProjectRequest :: ProjectId -> AccessToken -> (String, String) -> String -> (String, String) -> Request

-- | Construct a Google API request.
makeRequest :: AccessToken -> (String, String) -> String -> (String, String) -> Request

-- | Prepare a string for inclusion in a request.
makeRequestValue :: String -> ByteString
instance DoRequest JSValue
instance DoRequest Element
instance DoRequest ()
instance DoRequest [(String, String)]
instance DoRequest String
instance DoRequest ByteString


-- | Functions for accessing the unofficial Google Bookmarks API, see
--   <a>http://www.mmartins.com/mmartins/googlebookmarksapi/</a>.
module Network.Google.Bookmarks

-- | Google e-mail address.
type EMail = String

-- | Google password.
type Password = String

-- | SMS authentication token.
type SmsToken = String

-- | List the bookmarks, see
--   <a>http://www.mmartins.com/mmartins/googlebookmarksapi/</a>.
listBookmarks :: EMail -> Password -> SmsToken -> IO Element


-- | Functions for the Google Books API, see
--   <a>https://developers.google.com/books/docs/v1/using#WorkingMyBookshelves</a>.
module Network.Google.Books

-- | Bookshelf ID.
type ShelfId = String

-- | List the books, see
--   <a>https://developers.google.com/books/docs/v1/using#RetrievingMyBookshelfVolumes</a>.
listBooks :: AccessToken -> [ShelfId] -> IO JSValue

-- | List the bookshelves, see
--   <a>https://developers.google.com/books/docs/v1/using#RetrievingMyBookshelves</a>.
listBookshelves :: AccessToken -> IO JSValue


-- | Functions for accessing the Fusion Tables API, see
--   <a>https://developers.google.com/fusiontables/</a>.
--   
--   This provides a very limited subset of the complete (v1) API at
--   present.
module Network.Google.FusionTables

-- | ID for a specific fusion table
type TableId = FTString

-- | An incomplete representation of
--   <a>https://developers.google.com/fusiontables/docs/v1/reference/table#resource</a>
data TableMetadata
TableMetadata :: FTString -> FTString -> [ColumnMetadata] -> TableMetadata
tab_name :: TableMetadata -> FTString
tab_tableId :: TableMetadata -> FTString
tab_columns :: TableMetadata -> [ColumnMetadata]
data ColumnMetadata
ColumnMetadata :: Int -> FTString -> FTString -> ColumnMetadata
col_columnId :: ColumnMetadata -> Int
col_name :: ColumnMetadata -> FTString
col_type :: ColumnMetadata -> FTString

-- | Designed to mirror the types listed here:
--   <a>https://developers.google.com/fusiontables/docs/v1/reference/column</a>
data CellType
NUMBER :: CellType
STRING :: CellType
LOCATION :: CellType
DATETIME :: CellType

-- | Create an (exportable) table with a given name and list of columns.
createTable :: AccessToken -> String -> [(FTString, CellType)] -> IO TableMetadata

-- | Create a new column in a given table. Returns the metadata for the new
--   column.
createColumn :: AccessToken -> TableId -> (FTString, CellType) -> IO ColumnMetadata

-- | List all tables belonging to a user. See
--   <a>https://developers.google.com/fusiontables/docs/v1/reference/table/list</a>.
listTables :: AccessToken -> IO [TableMetadata]

-- | List the columns within a specific table. See
--   <a>https://developers.google.com/fusiontables/docs/v1/reference/column/list</a>.
listColumns :: AccessToken -> TableId -> IO [ColumnMetadata]

-- | Insert one or more rows into a table. Rows are represented as lists of
--   strings. The columns being written are passed in as a separate list.
--   The length of all rows must match eachother and must match the list of
--   column names.
--   
--   NOTE: this method has a major limitation. SQL queries are encoded into
--   the URL, and it is very easy to exceed the maximum URL length accepted
--   by Google APIs.
insertRows :: AccessToken -> TableId -> [FTString] -> [[FTString]] -> IO ()

-- | Implement a larger quantity of rows, but with the caveat that the
--   number and order of columns must exactly match the schema of the
--   fusion table on the server. <a>bulkImportRows</a> will perform a
--   listing of the columns to verify this before uploading.
--   
--   This function also checks that the server reports receiving the same
--   number of rows as were uploaded.
--   
--   NOTE: also use this function for LONG rows, even if there is only one.
--   Really, you should almost always use this function rather thna
--   <a>insertRows</a>.
bulkImportRows :: AccessToken -> TableId -> [FTString] -> [[FTString]] -> IO ()
getData :: AccessToken -> String -> String -> Maybe String -> IO ColData
data ColData
ColData :: [FTString] -> [[FTValue]] -> ColData
colName :: ColData -> [FTString]
values :: ColData -> [[FTValue]]
data FTValue
StringValue :: FTString -> FTValue
DoubleValue :: Double -> FTValue
tableSelect :: AccessToken -> String -> String -> Maybe String -> IO ColData

-- | Run a supported SQL query to retrieve data from a fusion table.
tableSQLQuery :: AccessToken -> String -> String -> IO ColData
instance Eq ColumnMetadata
instance Show ColumnMetadata
instance Read ColumnMetadata
instance Ord ColumnMetadata
instance Generic ColumnMetadata
instance Eq TableMetadata
instance Show TableMetadata
instance Read TableMetadata
instance Ord TableMetadata
instance Generic TableMetadata
instance Show CellType
instance Eq CellType
instance Ord CellType
instance Read CellType
instance Eq FTValue
instance Show FTValue
instance Eq ColData
instance Show ColData
instance Datatype D1ColumnMetadata
instance Constructor C1_0ColumnMetadata
instance Selector S1_0_0ColumnMetadata
instance Selector S1_0_1ColumnMetadata
instance Selector S1_0_2ColumnMetadata
instance Datatype D1TableMetadata
instance Constructor C1_0TableMetadata
instance Selector S1_0_0TableMetadata
instance Selector S1_0_1TableMetadata
instance Selector S1_0_2TableMetadata
instance Out ColumnMetadata
instance Out TableMetadata


-- | Functions for OAuth 2.0 authentication for Google APIs.
--   
--   If you are new to Google web API's, bear in mind that there are
--   <i>three</i> different methods for accessing APIs (installed
--   applications, web apps, service-to-service), and this library is most
--   useful for "installed applications".
--   
--   Installed applications need the user to grant permission in a browser
--   at least once (see <a>formUrl</a>). However, while the resulting
--   <a>accessToken</a> expires quickly, the <a>refreshToken</a> can be
--   used indefinitely for retrieving new access tokens. Thus this approach
--   can be suitable for long running or periodic programs that access
--   Google data.
--   
--   Below is a quick-start program which will list any Google Fusion
--   tables the user possesses. It requires the client ID and secret
--   retrieved from <a>https://code.google.com/apis/console</a>.
--   
--   <pre>
--   import Control.Monad (unless)
--   import System.Info (os)
--   import System.Process (system, rawSystem)
--   import System.Exit    (ExitCode(..))
--   import System.Directory (doesFileExist)
--   import Network.Google.OAuth2 (formUrl, exchangeCode, refreshTokens,
--                                 OAuth2Client(..), OAuth2Tokens(..))
--   import Network.Google (makeRequest, doRequest)
--   import Network.HTTP.Conduit (simpleHttp)
--   --
--   cid    = "INSTALLED_APP_CLIENT_ID"
--   secret = "INSTALLED_APP_SECRET_HERE"
--   file   = "./tokens.txt"
--   --  
--   main = do
--     -- Ask for permission to read/write your fusion tables:
--     let client = OAuth2Client { clientId = cid, clientSecret = secret }
--         permissionUrl = formUrl client ["https:/<i>www.googleapis.com</i>auth/fusiontables"]
--     b &lt;- doesFileExist file
--     unless b $ do 
--         putStrLn$ "Load this URL: "++show permissionUrl
--         case os of
--           "linux"  -&gt; rawSystem "gnome-open" [permissionUrl]
--           "darwin" -&gt; rawSystem "open"       [permissionUrl]
--           _        -&gt; return ExitSuccess
--         putStrLn "Please paste the verification code: "
--         authcode &lt;- getLine
--         tokens   &lt;- exchangeCode client authcode
--         putStrLn$ "Received access token: "++show (accessToken tokens)
--         tokens2  &lt;- refreshTokens client tokens
--         putStrLn$ "As a test, refreshed token: "++show (accessToken tokens2)
--         writeFile file (show tokens2)
--     accessTok &lt;- fmap (accessToken . read) (readFile file)
--     putStrLn "As a test, list the users tables:"
--     response &lt;- simpleHttp ("https:/<i>www.googleapis.com</i>fusiontables<i>v1</i>tables?access_token="++accessTok)
--     putStrLn$ BL.unpack response
--   </pre>
module Network.Google.OAuth2
data OAuth2Client
OAuth2Client :: String -> String -> OAuth2Client

-- | The client ID.
clientId :: OAuth2Client -> String

-- | The client secret.
clientSecret :: OAuth2Client -> String

-- | An OAuth 2.0 scope.
type OAuth2Scope = String

-- | OAuth 2.0 tokens.
data OAuth2Tokens
OAuth2Tokens :: String -> String -> Rational -> String -> OAuth2Tokens

-- | The access token.
accessToken :: OAuth2Tokens -> String

-- | The refresh token.
refreshToken :: OAuth2Tokens -> String

-- | The number of seconds until the access token expires.
expiresIn :: OAuth2Tokens -> Rational

-- | The token type.
tokenType :: OAuth2Tokens -> String

-- | The OAuth 2.0 scopes for Google APIs, see
--   <a>https://developers.google.com/oauthplayground/</a>.
googleScopes :: [(String, OAuth2Scope)]

-- | Form a URL for authorizing an installed application, see
--   <a>https://developers.google.com/accounts/docs/OAuth2InstalledApp#formingtheurl</a>.
formUrl :: OAuth2Client -> [OAuth2Scope] -> String

-- | Exchange an authorization code for tokens, see
--   <a>https://developers.google.com/accounts/docs/OAuth2InstalledApp#handlingtheresponse</a>.
exchangeCode :: OAuth2Client -> OAuth2Code -> IO OAuth2Tokens

-- | Refresh OAuth 2.0 tokens, see
--   <a>https://developers.google.com/accounts/docs/OAuth2InstalledApp#refresh</a>.
refreshTokens :: OAuth2Client -> OAuth2Tokens -> IO OAuth2Tokens

-- | Validate OAuth 2.0 tokens, see
--   <a>https://developers.google.com/accounts/docs/OAuth2Login#validatingtoken</a>.
validateTokens :: OAuth2Tokens -> IO Rational

-- | Provide a hassle-free way to retrieve and refresh tokens from a users
--   home directory, OR ask the user for permission.
--   
--   The first time it is called, this may open a web-browser, and/or
--   request the user enter data on the command line. Subsequently,
--   invocations on the same machine should not communicate with the user.
--   
--   If the tokens do not expire until more than 15 minutes in the future,
--   this procedure will skip the refresh step. Whether or not it refreshes
--   should be immaterial to the clients subsequent actions, because all
--   clients should handle authentication errors (and all 5xx errors) and
--   call <a>refreshToken</a> as necessary.
getCachedTokens :: OAuth2Client -> IO OAuth2Tokens
instance Read OAuth2Client
instance Show OAuth2Client
instance Read OAuth2Tokens
instance Show OAuth2Tokens


-- | Functions for accessing the Picasa API, see
--   <a>https://developers.google.com/picasa-web/docs/2.0/developers_guide_protocol</a>.
module Network.Google.Picasa

-- | Picasa user ID.
type UserId = String

-- | Default Picasa user ID
defaultUser :: UserId

-- | Picasa album ID.
type AlbumId = String

-- | List the albums, see
--   <a>https://developers.google.com/picasa-web/docs/2.0/developers_guide_protocol#ListAlbums</a>.
listAlbums :: AccessToken -> UserId -> IO Element

-- | List the photos in albums, see
--   <a>https://developers.google.com/picasa-web/docs/2.0/developers_guide_protocol#ListAlbumPhotos</a>.
listPhotos :: AccessToken -> UserId -> [AlbumId] -> IO Element


-- | Miscellaneous functions for MD5 checksums.
module Crypto.MD5

-- | MD5 checksum information.
type MD5Info = (MD5String, MD5Base64)

-- | An MD5 checksum represented as a character string.
type MD5String = String

-- | An MD5 checksum represented in base 64 encoding.
type MD5Base64 = String

-- | After finalizing a context, using md5Finalize, a new type is returned
--   to prevent 're-finalizing' the structure.
data MD5Digest :: *

-- | Processes a lazy ByteString and returns the md5 digest. This is
--   probably what you want.
md5 :: ByteString -> MD5Digest

-- | Compute an MD5 checksum.
md5Base64 :: ByteString -> MD5Info

-- | Convert an MD5 digest into a base-64-encoded string.
md5ToBase64 :: MD5Digest -> MD5Base64

-- | The MD5 info for an empty string.
md5Empty :: MD5Info


-- | Functions for the Google Storage API, see
--   <a>https://developers.google.com/storage/docs/reference-methods</a>.
module Network.Google.Storage

-- | A bucket name.
type BucketName = String

-- | A key name for an object.
type KeyName = String

-- | Access control.
data StorageAcl
Private :: StorageAcl
PublicRead :: StorageAcl
PublicReadWrite :: StorageAcl
AuthenicatedRead :: StorageAcl
BucketOwnerRead :: StorageAcl
BucketOwnerFullControl :: StorageAcl

-- | MIME type.
type MIMEType = String

-- | List all of the buckets in a specified project. This performs the "GET
--   Service" request, see
--   <a>https://developers.google.com/storage/docs/reference-methods#getservice</a>.
getService :: ProjectId -> AccessToken -> IO Element

-- | List all of the buckets in a specified project. This performs the "GET
--   Service" request, see
--   <a>https://developers.google.com/storage/docs/reference-methods#getservice</a>.
getServiceUsingManager :: Manager -> ProjectId -> AccessToken -> IO Element

-- | Creates a bucket in a specified project. This performs the "PUT
--   Bucket" request, see
--   <a>https://developers.google.com/storage/docs/reference-methods#putbucket</a>.
putBucket :: ProjectId -> StorageAcl -> BucketName -> AccessToken -> IO [(String, String)]

-- | Creates a bucket in a specified project. This performs the "PUT
--   Bucket" request, see
--   <a>https://developers.google.com/storage/docs/reference-methods#putbucket</a>.
putBucketUsingManager :: Manager -> ProjectId -> StorageAcl -> BucketName -> AccessToken -> IO [(String, String)]

-- | Lists the objects that are in a bucket. This performs the "GET Bucket"
--   request, see
--   <a>https://developers.google.com/storage/docs/reference-methods#getbucket</a>.
getBucket :: ProjectId -> BucketName -> AccessToken -> IO Element

-- | Lists the objects that are in a bucket. This performs the "GET Bucket"
--   request, see
--   <a>https://developers.google.com/storage/docs/reference-methods#getbucket</a>.
getBucketUsingManager :: Manager -> ProjectId -> BucketName -> AccessToken -> IO Element

-- | Deletes an empty bucket. This performs the "DELETE Bucket" request,
--   see
--   <a>https://developers.google.com/storage/docs/reference-methods#deletebucket</a>.
deleteBucket :: ProjectId -> BucketName -> AccessToken -> IO [(String, String)]

-- | Deletes an empty bucket. This performs the "DELETE Bucket" request,
--   see
--   <a>https://developers.google.com/storage/docs/reference-methods#deletebucket</a>.
deleteBucketUsingManager :: Manager -> ProjectId -> BucketName -> AccessToken -> IO [(String, String)]

-- | Downloads an object. This performs the "GET Object" request, see
--   <a>https://developers.google.com/storage/docs/reference-methods#getobject</a>.
getObject :: ProjectId -> BucketName -> KeyName -> AccessToken -> IO ByteString

-- | Downloads an object. This performs the "GET Object" request, see
--   <a>https://developers.google.com/storage/docs/reference-methods#getobject</a>.
getObjectUsingManager :: Manager -> ProjectId -> BucketName -> KeyName -> AccessToken -> IO ByteString

-- | Uploads an object. This performs the "PUT Object" request, see
--   <a>https://developers.google.com/storage/docs/reference-methods#putobject</a>.
putObject :: ProjectId -> StorageAcl -> BucketName -> KeyName -> Maybe MIMEType -> ByteString -> Maybe MD5Info -> AccessToken -> IO [(String, String)]

-- | Uploads an object. This performs the "PUT Object" request, see
--   <a>https://developers.google.com/storage/docs/reference-methods#putobject</a>.
putObjectUsingManager :: Manager -> ProjectId -> StorageAcl -> BucketName -> KeyName -> Maybe MIMEType -> ByteString -> Maybe MD5Info -> AccessToken -> IO [(String, String)]

-- | Lists metadata for an object. This performs the "HEAD Object" request,
--   see
--   <a>https://developers.google.com/storage/docs/reference-methods#headobject</a>.
headObject :: ProjectId -> BucketName -> KeyName -> AccessToken -> IO [(String, String)]

-- | Lists metadata for an object. This performs the "HEAD Object" request,
--   see
--   <a>https://developers.google.com/storage/docs/reference-methods#headobject</a>.
headObjectUsingManager :: Manager -> ProjectId -> BucketName -> KeyName -> AccessToken -> IO [(String, String)]

-- | Deletes an object. This performs the "DELETE Object" request, see
--   <a>https://developers.google.com/storage/docs/reference-methods#deleteobject</a>.
deleteObject :: ProjectId -> BucketName -> KeyName -> AccessToken -> IO [(String, String)]

-- | Deletes an object. This performs the "DELETE Object" request, see
--   <a>https://developers.google.com/storage/docs/reference-methods#deleteobject</a>.
deleteObjectUsingManager :: Manager -> ProjectId -> BucketName -> KeyName -> AccessToken -> IO [(String, String)]
instance Bounded StorageAcl
instance Enum StorageAcl
instance Eq StorageAcl
instance Read StorageAcl
instance Show StorageAcl


-- | Interface to GnuPG. The GnuPG program "gpg" must be on the PATH.
module Crypto.GnuPG

-- | A recipient for encryption.
type Recipient = String

-- | Decrypt text.
decrypt :: String -> IO String

-- | Decrypt binary data.
decryptLbs :: ByteString -> IO ByteString

-- | Encrypt text.
encrypt :: [Recipient] -> String -> IO String

-- | Encrypt binary data.
encryptLbs :: [Recipient] -> ByteString -> IO ByteString


-- | Functions for accessing the Google Contacts API, see
--   <a>https://developers.google.com/google-apps/contacts/v3/</a>.
module Network.Google.Contacts

-- | List the contacts, see
--   <a>https://developers.google.com/google-apps/contacts/v3/#retrieving_all_contacts</a>.
listContacts :: AccessToken -> IO Element

-- | Extract the GnuPG/PGP text in the "Notes" fields of a contact list.
--   Extracts are re-encrypted if recipients for the re-encrypted list are
--   specified.
extractGnuPGNotes :: [Recipient] -> Element -> IO String


-- | Functions for putting and getting GnuPG-encrypted objects in Google
--   Storage.
module Network.Google.Storage.Encrypted

-- | Encrypt an object and upload it.
putEncryptedObject :: [Recipient] -> ProjectId -> StorageAcl -> BucketName -> KeyName -> Maybe MIMEType -> ByteString -> Maybe MD5Info -> AccessToken -> IO [(String, String)]
putEncryptedObjectUsingManager :: Manager -> [Recipient] -> ProjectId -> StorageAcl -> BucketName -> KeyName -> Maybe MIMEType -> ByteString -> Maybe MD5Info -> AccessToken -> IO [(String, String)]

-- | Downloads an object and decrypts it.
getEncryptedObject :: ProjectId -> BucketName -> KeyName -> AccessToken -> IO ByteString

-- | Downloads an object and decrypts it.
getEncryptedObjectUsingManager :: Manager -> ProjectId -> BucketName -> KeyName -> AccessToken -> IO ByteString


-- | Synchronization of filesystem directories with Google Storage buckets.
module Network.Google.Storage.Sync

-- | A regular expression used for excluding files from synchronization.
type RegexExclusion = String

-- | Synchronize a filesystem directory with a Google Storage bucket.
sync :: ProjectId -> StorageAcl -> BucketName -> OAuth2Client -> OAuth2Tokens -> FilePath -> [Recipient] -> [RegexExclusion] -> Bool -> Bool -> IO ()
instance Show ObjectMetadata
instance Eq ObjectMetadata
instance Ord ObjectMetadata