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


-- | A library to access the Dropbox HTTP API.
--   
--   A (very preliminary) library to access the Dropbox HTTP API:
--   <a>https://www.dropbox.com/developers/reference/api</a>
@package dropbox-sdk
@version 0.2.0

module Dropbox

-- | A convenience function that constructs a <a>Config</a>. It's in the
--   <a>IO</a> monad because we read from a file to get the list of trusted
--   SSL certificates, which is used to verify the server over SSL.
mkConfig :: Locale -> String -> String -> AccessType -> IO Config

-- | The configuration used to make API calls. You typically create one of
--   these via the <tt>config</tt> helper function.
data Config
Config :: Hosts -> Locale -> AppId -> AccessType -> CertVerifier -> Config

-- | The hosts to connect to (just use <a>hostsDefault</a>).
configHosts :: Config -> Hosts

-- | The locale that the Dropbox service should use when returning
--   user-visible strings.
configUserLocale :: Config -> Locale

-- | Your app's key/secret
configAppId :: Config -> AppId

-- | The type of folder access your Dropbox application uses.
configAccessType :: Config -> AccessType

-- | The server certificate validation routine.
configCertVerifier :: Config -> CertVerifier

-- | How the server's SSL certificate will be verified.
data CertVerifier
CertVerifier :: String -> CertVerifierFunc -> CertVerifier

-- | The human-friendly name of the policy (only for debug prints)
certVerifierName :: CertVerifier -> String

-- | The function that implements certificate validation.
certVerifierFunc :: CertVerifier -> CertVerifierFunc

-- | A dummy implementation that doesn't perform any verification.
certVerifierInsecure :: CertVerifier

-- | Reads certificates in PEM format from the given file and uses those as
--   the roots when verifying certificates. This function basically just
--   loads the certificates and delegates to
--   <a>certVerifierFromRootCerts</a> for the actual checking.
certVerifierFromPemFile :: FilePath -> IO (Either ErrorMessage CertVerifier)

-- | A certificate validation routine. It's in <a>IO</a> to match what
--   <tt>HTTP.Enumerator</tt> expects, but we don't actually do any I/O.
certVerifierFromRootCerts :: [X509] -> Ascii -> [X509] -> IO TLSCertificateUsage

-- | Your application's Dropbox "app key" and "app secret".
data AppId
AppId :: String -> String -> AppId

-- | The set of hosts that serve the Dropbox API. Just use
--   <a>hostsDefault</a>.
data Hosts
Hosts :: String -> String -> String -> Hosts

-- | The Dropbox API web host (for OAuth step 2)
hostsWeb :: Hosts -> String

-- | The Dropbox API endpoint for most non-content-transferring calls.
hostsApi :: Hosts -> String

-- | The Dropbox API endpoint for most content-transferring calls.
hostsApiContent :: Hosts -> String

-- | The standard set of hosts that serve the Dropbox API. Used to create a
--   <a>Config</a>.
hostsDefault :: Hosts

-- | Specifies a locale (the string is a two-letter locale code)
data Locale

-- | English (American) ("en").
localeEn :: Locale

-- | Spanish ("es").
localeEs :: Locale

-- | French ("fr").
localeFr :: Locale

-- | German ("de").
localeDe :: Locale

-- | Japanese ("jp").
localeJp :: Locale

-- | The type of folder access your Dropbox application uses
--   (<a>https://www.dropbox.com/developers/start/core</a>).
data AccessType

-- | Full access to the user's entire Dropbox
AccessTypeDropbox :: AccessType

-- | Access to an application-specific "app folder" within the user's
--   Dropbox
AccessTypeAppFolder :: AccessType

-- | The HTTP connection manager. Using the same <a>Manager</a> instance
--   across multiple API calls
type Manager = Manager

-- | A bracket around an HTTP connection manager.
withManager :: (Manager -> IO r) -> IO r

-- | An OAuth request token (returned by <a>authStart</a>)
data RequestToken
RequestToken :: String -> String -> RequestToken

-- | OAuth step 1. If successful, returns a <a>RequestToken</a> (to be used
--   with <a>authFinish</a> eventually) and an authorization URL that you
--   should redirect the user to next. If you provide a callback URL
--   (optional), then the authorization URL you send the user to will
--   redirect to your callback URL after the user authorizes your
--   application.
authStart :: Manager -> Config -> Maybe URL -> IO (Either ErrorMessage (RequestToken, URL))

-- | An OAuth request token (returned by <a>authFinish</a>, used to
--   construct a <a>Session</a>)
data AccessToken
AccessToken :: String -> String -> AccessToken

-- | OAuth step 3. Once you've directed the user to the authorization URL
--   from <a>authStart</a> and the user has authorized your app, call this
--   function to get a <a>RequestToken</a>, which is used to make Dropbox
--   API calls.
authFinish :: Manager -> Config -> RequestToken -> IO (Either ErrorMessage (AccessToken, String))

-- | Contains a <a>Config</a> and an <a>AccessToken</a>. Every API call
--   (after OAuth is complete) requires this as an argument.
data Session
Session :: Config -> AccessToken -> Session
sessionConfig :: Session -> Config

-- | The <a>AccessToken</a> obtained from <a>authFinish</a>
sessionAccessToken :: Session -> AccessToken

-- | Retrieve information about the user account your <a>AccessToken</a> is
--   connected to.
getAccountInfo :: Manager -> Session -> IO (Either ErrorMessage AccountInfo)

-- | Information about a user account.
data AccountInfo
AccountInfo :: Word64 -> String -> Maybe String -> String -> Quota -> AccountInfo

-- | Dropbox user ID
accountInfoUid :: AccountInfo -> Word64

-- | Full name (when displayed as a single string)
accountInfoDisplayName :: AccountInfo -> String

-- | Two-letter country code, if available
accountInfoCountry :: AccountInfo -> Maybe String

-- | Dropbox referral link
accountInfoReferralUrl :: AccountInfo -> String

-- | Information about the storage quota
accountInfoQuota :: AccountInfo -> Quota

-- | Get the metadata for the file or folder at the given path.
getMetadata :: Manager -> Session -> Path -> IO (Either ErrorMessage Meta)

-- | Get the metadata for the file or folder at the given path. If it's a
--   folder, return the metadata for the folder's immediate children as
--   well.
getMetadataWithChildren :: Manager -> Session -> Path -> Maybe Integer -> IO (Either ErrorMessage (Meta, Maybe FolderContents))

-- | Same as <a>getMetadataWithChildren</a> except it'll return
--   <tt>Nothing</tt> if the <a>FolderHash</a> of the folder on Dropbox is
--   the same as the <a>FolderHash</a> passed in.
getMetadataWithChildrenIfChanged :: Manager -> Session -> Path -> Maybe Integer -> FolderHash -> IO (Either ErrorMessage (Maybe (Meta, Maybe FolderContents)))

-- | The metadata for a file or folder. <a>MetaBase</a> contains the
--   metadata common to files and folders. <a>MetaExtra</a> contains the
--   file-specific or folder-specific data.
data Meta
Meta :: MetaBase -> MetaExtra -> Meta

-- | Metadata common to both files and folders.
data MetaBase
MetaBase :: AccessType -> String -> Bool -> Bool -> String -> MetaBase

-- | Matches the <a>AccessType</a> of the app that retrieved the metadata.
metaRoot :: MetaBase -> AccessType

-- | The full path (starting with a "/") of the file or folder, relative to
--   <a>metaRoot</a>
metaPath :: MetaBase -> String

-- | Whether this metadata entry refers to a file that had been deleted
--   when the entry was retrieved.
metaIsDeleted :: MetaBase -> Bool

-- | Will be <tt>True</tt> if this file might have a thumbnail, and
--   <tt>False</tt> if it definitely doesn't.
metaThumbnail :: MetaBase -> Bool

-- | The name of the icon used to illustrate this file type in Dropbox's
--   icon library
--   (<a>https://www.dropbox.com/static/images/dropbox-api-icons.zip</a>).
metaIcon :: MetaBase -> String

-- | Extra metadata (in addition to the stuff that's common to files and
--   folders).
data MetaExtra

-- | Files have additional metadata
File :: FileExtra -> MetaExtra

-- | Folders do not have any additional metadata
Folder :: MetaExtra

-- | The metadata for the immediate children of a folder.
data FolderContents
FolderContents :: FolderHash -> [Meta] -> FolderContents

-- | An identifier for the folder's metadata and children's metadata.
folderHash :: FolderContents -> FolderHash

-- | The metadata for the immediate children of a folder.
folderChildren :: FolderContents -> [Meta]

-- | Extra metadata specific to files (and not folders)
data FileExtra
FileExtra :: Integer -> String -> FileRevision -> UTCTime -> FileExtra

-- | The file size (bytes)
fileBytes :: FileExtra -> Integer

-- | A human-readable representation of the file size, for example <a>15
--   bytes</a> (localized according to <a>Locale</a> in <a>Config</a>)
fileHumanSize :: FileExtra -> String

-- | The revision of the file
fileRevision :: FileExtra -> FileRevision

-- | When this file was added or last updated
fileModified :: FileExtra -> UTCTime

-- | Represents an identifier for a folder's metadata and children's
--   metadata. Can be used with <a>getMetadataWithChildrenIfChanged</a> to
--   avoid downloading a folder's metadata and children's metadata if it
--   hasn't changed.
newtype FolderHash
FolderHash :: String -> FolderHash

-- | Represents a file's revision (<a>fileRevision</a>).
newtype FileRevision
FileRevision :: String -> FileRevision

-- | Gets a file's contents and metadata. If you just want the entire
--   contents of a file as a single <a>ByteString</a>, use
--   <a>getFileBs</a>.
getFile :: Manager -> Session -> Path -> Maybe FileRevision -> (Meta -> Sink ByteString IO r) -> IO (Either ErrorMessage (Meta, r))

-- | A variant of <a>getFile</a> that just returns a strict
--   <a>ByteString</a> (instead of having you pass in a <a>Sink</a> to
--   process the body.
getFileBs :: Manager -> Session -> Path -> Maybe FileRevision -> IO (Either ErrorMessage (Meta, ByteString))

-- | Add a new file. If a file or folder already exists at the given path,
--   your file will be automatically renamed. If successful, you'll get
--   back the metadata for your newly-uploaded file.
addFile :: Manager -> Session -> Path -> RequestBody -> IO (Either ErrorMessage Meta)

-- | Add a file. If a file already exists at the given path, that file will
--   be overwritten. If successful, you'll get back the metadata for your
--   newly-uploaded file.
forceFile :: Manager -> Session -> Path -> RequestBody -> IO (Either ErrorMessage Meta)

-- | Overwrite a file with new data if the version on Dropbox matches the
--   version you specify. If the version doesn't match, create a new file
--   with a unique name. Either way, you will be returned the metdata for
--   whichever file was written.
updateFile :: Manager -> Session -> Path -> RequestBody -> FileRevision -> IO (Either ErrorMessage Meta)
fileRevisionToString :: FileRevision -> String
folderHashToString :: FolderHash -> String
type ErrorMessage = String
type URL = String

-- | Dropbox file and folder paths. Should always start with <a>/</a>.
type Path = String

-- | An HTTP request body: an <a>Int64</a> for the length and a
--   <a>Source</a> that yields the actual data.
data RequestBody
RequestBody :: Int64 -> (Source IO ByteString) -> RequestBody

-- | Create a <a>RequestBody</a> from a single <a>ByteString</a>
bsRequestBody :: ByteString -> RequestBody

-- | A <a>Sink</a> that reads in <a>ByteString</a> chunks and constructs
--   one concatenated <a>ByteString</a>
bsSink :: Resource m => Sink ByteString m ByteString
instance Show AccessType
instance Eq AccessType
instance Show AppId
instance Eq AppId
instance Show RequestToken
instance Eq RequestToken
instance Show AccessToken
instance Eq AccessToken
instance Show Hosts
instance Eq Hosts
instance Show Locale
instance Eq Locale
instance Show Config
instance Show Quota
instance Eq Quota
instance Show AccountInfo
instance Eq AccountInfo
instance Eq MetaBase
instance Show MetaBase
instance Eq FileRevision
instance Show FileRevision
instance Eq FileExtra
instance Show FileExtra
instance Eq MetaExtra
instance Show MetaExtra
instance Eq Meta
instance Show Meta
instance Eq FolderHash
instance Show FolderHash
instance Eq FolderContents
instance Show FolderContents
instance JSON MetaWithChildren
instance JSON Meta
instance JSON Quota
instance JSON AccountInfo
instance Show CertVerifier