// -----------------------------------------------------------------------------
// Enum Typedefs
// -----------------------------------------------------------------------------

/**
 * Your add-on must declare the scopes it requires based on which API endpoints it needs to use, via its descriptor.
 * @typedef {"send_message" | "send_notification"} HipchatScope
 */

// -----------------------------------------------------------------------------
// Model Typedefs
// -----------------------------------------------------------------------------

/**
 * A request semantic failure reason.
 * @typedef {Object} Error
 * @property {string} description
 */

/**
 * @typedef {Object} HipchatApiConsumer
 * @property {HipchatScope[]} scopes An array of scopes that are required to consume the HipChat API.
 * @property {string} [fromName] The name that messages should be from when sent from the integration itself.
 */

/**
 * @typedef {Object} HipchatCapabilities
 * @property {HipchatConfigurationPage} [configurable] Most integrations will need to be configured in order to work correctly. For this purpose, an integration can expose a 'configurable' capability that provides an HTML page to be included as a panel in the configuration dialog.
 * @property {HipchatApiConsumer} [hipchatApiConsumer] The ability to consume the HipChat API.
 * @property {HipchatInstallable} [installable] The capability of receiving a synchronous installation callback during integration installation.
 * @property {HipchatOauth2Provider} [oauth2Provider] The capability of providing and accepting OAuth 2 tokens for authentication.
 */

/**
 * @typedef {Object} HipchatCapabilitiesDescriptor
 * @property {string} name The display name of this application.
 * @property {string} description A short description of this application.
 * @property {string} key The marketplace integration key that uniquely identifies the application, if registered.
 * @property {string} [apiVersion] The HipChat Connect API version used by this integration. Defaults to 1:1.
 * @property {HipchatCapabilities} [capabilities] The set of capabilities this application supports.
 * @property {HipchatLinks} links URLs to retrieve this and related integration information.
 * @property {HipchatVendor} [vendor] The vendor that maintains this application.
 */

/**
 * @typedef {Object} HipchatConfigurationPage
 * @property {string} [allowAccessToRoomAdmins] If the add-on is installed globally, this property can allow the configuration page to be accessed in the room administration pages making it possible to have room specific configuration for the global add-on. This is only valid for globally installed add-ons.
 * @property {string} url The URL to embed into a configure dialog via an iframe.
 */

/**
 * @typedef {Object} HipchatInstallData
 * @property {string} capabilitiesUrl
 * @property {string} oauthId
 * @property {string} oauthSecret
 * @property {number} groupId
 * @property {string} [roomId]
 */

/**
 * @typedef {Object} HipchatInstallable
 * @property {string} [callbackUrl] The URL to receive a confirmation of an integration installation.
 * @property {string} [installedUrl] The URL HipChat will redirect to post-installation.
 * @property {boolean} [allowGlobal] Whether the integration can be installed globally or not.
 * @property {boolean} [allowRoom] Whether the integration can be installed in a room or not.
 */

/**
 * @typedef {Object} HipchatLinks
 * @property {string} [homepage] The URL to human-viewable home page of this integration.
 * @property {string} [api] The URL to the REST API root.
 * @property {string} self The URL to this descriptor.
 */

/**
 * @typedef {Object} HipchatOauth2Provider
 * @property {string} [tokenUrl] The OAuth 2 token endpoint for retrieving an access token.
 * @property {string} [authorizationUrl] The OAuth 2 endpoint to direct browsers to in order to receive an authorization code that can be later exchanged using the token URL for an access token.
 */

/**
 * @typedef {Object} HipchatVendor
 * @property {string} name The vendor display name.
 * @property {string} url The vendor's home page URL.
 */

/**
 * @typedef {Object} ServiceInfo
 * @property {string} name Name of this service.
 * @property {string} version Version of this service.
 * @property {string} scala_version Version of Scala this service is using.
 * @property {string} sbt_version Version of SBT used to build this service.
 * @property {string} build_time Time the service was built at.
 */

/**
 * @typedef {Object} SnsNotification
 * @property {string} Type The type of message. For a unsubscribe confirmation, the type is UnsubscribeConfirmation.
 * @property {string} MessageId A Universally Unique Identifier, unique for each message published. For a message that Amazon SNS resends during a retry, the message ID of the original message is used.
 * @property {string} TopicArn The Amazon Resource Name (ARN) for the topic that this endpoint has been unsubscribed from.
 * @property {string} Message A string that describes the message.
 * @property {string} Timestamp The time (GMT) when the unsubscribe confirmation was sent.
 * @property {string} SignatureVersion Version of the Amazon SNS signature used.
 * @property {string} Signature Base64-encoded 'SHA1withRSA' signature of the Message, MessageId, Type, Timestamp, and TopicArn values.
 * @property {string} SigningCertURL The URL to the certificate that was used to sign the message.
 * @property {string} [Token] A value you can use with the ConfirmSubscription action to re-confirm the subscription. Alternatively, you can simply visit the SubscribeURL.
 * @property {string} [Subject] The Subject parameter specified when the notification was published to the topic. Note that this is an optional parameter. If no Subject was specified, then this name/value pair does not appear in this JSON document.
 * @property {string} [SubscribeURL] The URL that you must visit in order to re-confirm the subscription. Alternatively, you can instead use the Token with the ConfirmSubscription action to re-confirm the subscription.
 * @property {string} [UnsubscribeURL] A URL that you can use to unsubscribe the endpoint from this topic. If you visit this URL, Amazon SNS unsubscribes the endpoint and stops sending notifications to this endpoint.
 */

// -----------------------------------------------------------------------------
// Union Typedefs
// -----------------------------------------------------------------------------