dropcam

Unofficial Dropcam API Client

Status

This project is deprecated and is no longer supported as of 3.1.3.

Features

• Dropcam Scope
  • Search API - Find any camera publically accessable
  • Demos API - Access various demos available
  • Camera API - Access various functions of a camera
    • User Scope
      • User API
        • Notification Email Management - Manage email notifications
        • User Creation (new) - Create new users
    • Camera Scope
      • Settings - View, manage and modify various camera settings including visibility
      • Screenshots - Capture live screenshots of the camera
      • Clips - View, manage, and modify available clips (update, delete, and download)
      • Notification Devices - View and modify devices that receive notifications to this camera
      • Basic implementation of Events - Get any motion/sound events that occur with this camera
      • Basic implementation of Subscriptions - Get all current subscriptions to this camera
      • ~~Media Capture - Capture real time screenshots and live video streams (requires RTMPDUMP)~~

TODO

• Subscriptions - Manage and modify subscriptions (partially implemented)
• Capture Video/Sound Streams with the ability to talkback
• Meaningful Events
• Tests using tape

Installation

$ git clone https://github.com/nlocnila/dropcam.git

Tests

$ npm test

Examples

See examples in the `examples` folder
- user.js - Example of calling existing user properties and methods
- create.js - Example of registering a new dropcam user
- demos.js - Example of calling all current dropcam demos
- search.js - Example of searching for a specific dropcam using a public token
- settings.js - Example of manipulating existing settings associated with your dropcam
- events.js - Example of listening for specific dropcam events such as motion or sound
- screenshot.js - Example of taking a screenshot of your camera, can be substituted as a live video stream if updated frequently
- devices.js - Example of managing device notifications
- clips.js - Example of managing existing clips
- subscriptions.js - Example of managing subscriptions to your camera 			

Dropcam API

.login(username, password, callback)

This function will attempt to login into the private dropcam API and returns a user (you) with a valid session if successful. This function takes three parameters, username, password, and callback. This is considered the main entry function and must be called before accessing any other APIs. See the examples folder to see an example.

.search(user, public_token, callback)

This function will attempt to search the dropcam API using the public token to find the camera that's associated with it. The function takes a user and public_token. The callback returns a camera if successful. Login must be called before accessing the full camera API. Note: You will not be able to modify camera settings (such as visibility) unless you own the camera. See examples/search.js to see an example.

.demos(user, callback)

This function will attempt to search for available demos and return an array of cameras. Login must be called before accessing the full camera API. The function takes a user. Note: You will not be able to modify camera settings (such as visibility) unless you own the camera. See examples/demos.js to see an example.

.getVisibleCameras(user, callback)

This function will attempt to return an array of visible cameras associated with the user. Login must be called before accessing the full camera API. See the examples folder to see an example.

User API

You can access several user properties and session details with a user.

.addNotificationEmail(email, callback)

This function will attempt to add a new email address for notifications and return an object containing the new address and id. The id is important to have in the case you wish to later remove the associated email. See examples/user.js to see an example.

.removeNotificationEmail(email_id, callback)

This function will attempt to remove an associated email address with the email_id and return a true/false depending on success. You can only obtain the id when you create a new notification email using the API, so it's important to save the id if you plan on removing it later. See examples/user.js to see an example.

.Register(username, password, email, callback)

This function registers a new user to dropcam. It takes three parameters, username, password, and email. Email validation is not included. See examples/create.js to see an example.

Camera API

Due to wide variety of properties and settings varying per camera, you can access all properties by extending the camera's properties, settings and user.

You can also call .on(event, callback) if you wish to receive the following motion/sound events. See below on how to capture these events.

Event: 'motion'

This event receives any motion events detected by this camera

Event: 'sound'

This event receives any sound events detected by this camera

Event: 'error'

This event receives any error events that occur

.toggle(visibility, callback)

This function will attempt to toggle the camera's visibility setting and return the resulting new setting as private or public. You can pass in a string such as private or public as the visibility parameter. Note: This function will not work on cameras not associated with the user. See examples/settings.js to see an example.

.update(keyvalue, callback)

This function will attempt to update a camera setting such as enabling audio, motion detection, etc and returns a true/false depending on the success. You can see a full list of available settings by accessing the settings property on the camera including their values. Note: This function will not work on cameras not associated with the user. See examples/settings.js to see an example.

.capture(callback)

This function will attempt to capture a live screenshot of the camera and return a screenshot object. This function should work on both user owned and public cameras. See examples/screenshot.js to see an example. PLEASE NOTE as of 2.0.3, screenshot streams are now accessed by the stream property.

.getNotificationDevices(callback)

This function will attempt to get all devices asssociated with this camera and return an array of devices that are currently recently notifications. Note: This function will not work on cameras not associated with the user. See examples/devices.js to see an example.

.getSubscriptions(callback)

This function will attempt to get any subscriptions associated with this camera and return an array of subscriptions. Note: This function will not work on cameras not associated with the user. See examples/subscriptions.js to see an example.

.getClips(callback)

This function will attempt to get any video clips saved on the cloud and return an array of clips. See examples/clips.js to see an example.

.listen(timeout)

This function will begin monitoring any motion/sound events that occur with this camera. You can optionally pass a timeout parameter in the case you want to increase/decrease frequency of API calls. The default delay is 1000 ms. Any events captured will be emitted as soon as the API knows of the event. Be aware of any delays such as latency to occur. See above for an example and which events can be captured.

Clips API

.download(callback)

This function will attempt to download a video clip. Returns an object containing the filename and stream. Stream contains video clip buffer. See examples\clips.js to see an example.

.update(keyvalue, callback)

This function will attempt to update any properties associated with the clip. The only properties that seem to be modifiable are title and description. Returns a true/false depending on success. See examples\clips.js to see an example.

.delete(callback)

This function will attempt to delete the clip. Returns true/false depending on success. Clip will no longer be usable at this point, call .getClips to refresh available clips. See examples\clips.js to see an example.

Devices API

.toggle(enable, callback)

This function enables or disables the device for receiving notifications, as in when something occurs that device will be notified. You will need to have the device's type and value in order to create and enable the device. Returns a true/false value depending on success. See above for an example. Tip: If you want to re-enable an existing device, you should consider persisting the object's properties by creating a new Device object. See the examples\device.js to see an example.

Breaking changes in 2.0.3

Screenshot and Clip streams can now be accessed using the stream property. Check out examples to see how its done.

Deprecated as of 1.0.0

.getDevicesWithNotifications

This function has been renamed to .getNotificationDevices

Deprecated as of 1.0.1

.getSessionToken

This function is no longer used; you can access the session token from User node directly via the session key.

Deprecated as of 2.0.3

.enable(callback)

.disable(callback)

These functions have been merged into a single toggle function. See above for an example.

Bugs/Errors

If you come across any errors, feel free to submit a new issue or pull request.

License

Copyright (c) 2014-2015 nlocnila

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.