 #   "aws2js": "0.7.10"
 #
 # Configuration:
-#   HUBOT_S3_BRAIN_ACCESS_KEY_ID
-#   HUBOT_S3_BRAIN_SECRET_ACCESS_KEY
-#   HUBOT_S3_BRAIN_BUCKET
+#   HUBOT_S3_BRAIN_ACCESS_KEY_ID      - AWS Access Key ID with S3 permissions
+#   HUBOT_S3_BRAIN_SECRET_ACCESS_KEY  - AWS Secret Access Key for ID
+#   HUBOT_S3_BRAIN_BUCKET             - Bucket to store brain in
+#   HUBOT_S3_BRAIN_SAVE_INTERVAL      - [Optional] auto-save interval in seconds
+#                                     Defaults to 30 minutes
 #
 # Commands:
 #
 # Notes:
+#   Take care if using this brain storage with other brain storages.  Others may
+#   set the auto-save interval to an undesireable value.  Since S3 requests have
+#   an associated monetary value, this script uses a 30 minute auto-save timer
+#   by default to reduce cost.
+#
 #   It's highly recommended to use an IAM account explicitly for this purpose
 #   https://console.aws.amazon.com/iam/home?
 #   A sample S3 policy for a bucket named Hubot-Bucket would be

util  = require 'util'
aws   = require 'aws2js'

# sets up hooks to persist the brain into redis.
module.exports = (robot) ->

  loaded            = false
  key               = process.env.HUBOT_S3_BRAIN_ACCESS_KEY_ID
  secret            = process.env.HUBOT_S3_BRAIN_SECRET_ACCESS_KEY
  bucket            = process.env.HUBOT_S3_BRAIN_BUCKET
  brain_dump_path   = "#{bucket}/brain-dump.json"

  if !key && !secret && !bucket
    throw new Error('S3 brain requires HUBOT_S3_BRAIN_ACCESS_KEY_ID, ' +
      'HUBOT_S3_BRAIN_SECRET_ACCESS_KEY and HUBOT_S3_BRAIN_BUCKET configured')

  s3 = aws.load('s3', key, secret)


  store_current_brain = () ->
    store_brain robot.brain.data

  s3.get brain_dump_path, 'buffer', (err, response) ->
    # unfortunately S3 gives us a 403 if we have access denied OR
    # the file is simply missing, so no way of knowing if IAM policy is bad
