WebDAV, CalDAV, and CardDAV client for nodejs and the browser
npm install dav-forkdav
===
WebDAV, CalDAV, and CardDAV client for nodejs and the browser.
Table of Contents generated with DocToc
- API
- accounts
- dav.createAccount(options)
- calendars
- dav.createCalendarObject(calendar, options)
- dav.updateCalendarObject(calendarObject, options)
- dav.deleteCalendarObject(calendarObject, options)
- dav.syncCalendar(calendar, options)
- dav.syncCaldavAccount(account, options)
- contacts
- dav.createCard(addressBook, options)
- dav.updateCard(card, options)
- dav.deleteCard(card, options)
- dav.syncAddressBook(addressBook, options)
- dav.syncCarddavAccount(account, options)
- sandbox
- dav.Sandbox()
- transport
- dav.transport.Basic(credentials)
- dav.transport.Basic.send(request, options)
- dav.transport.OAuth2(credentials)
- dav.transport.OAuth2.send(request, options)
- request
- dav.request.addressBookQuery(options)
- dav.request.basic(options)
- dav.request.calendarQuery(options)
- dav.request.propfind(options)
- dav.request.syncCollection(options)
- Client
- dav.Client(xhr, options)
- dav.Client.send(req, options)
- etc
- dav.ns
- Example Usage
- Using the lower-level webdav request api
- Debugging
Options:
(String) accountType - one of 'caldav' or 'carddav'. Defaults to 'caldav'.
(Array.`
$3
#### dav.createCalendarObject(calendar, options)
Create a calendar object on the parameter calendar. Returns a Promise which will be fulfilled when the calendar has been created.
`
@param {dav.Calendar} calendar the calendar to put the object on.
Options:
(String) data - rfc 5545 VCALENDAR object.
(String) filename - name for the calendar ics file.
(dav.Sandbox) sandbox - optional request sandbox.
(dav.Transport) xhr - request sender.
`
#### dav.updateCalendarObject(calendarObject, options)
Persist updates to the parameter calendar object to the server. Returns a Promise which will be fulfilled when the calendar has been updated.
`
@param {dav.CalendarObject} calendarObject updated calendar object.
Options:
(dav.Sandbox) sandbox - optional request sandbox.
(dav.Transport) xhr - request sender.
`
#### dav.deleteCalendarObject(calendarObject, options)
Delete the parameter calendar object on the server. Returns a Promise which will be fulfilled when the calendar has been deleted.
`
@param {dav.CalendarObject} calendarObject target calendar object.
Options:
(dav.Sandbox) sandbox - optional request sandbox.
(dav.Transport) xhr - request sender.
`
#### dav.syncCalendar(calendar, options)
Fetch changes from the remote server to the parameter calendar. Returns a Promise which will be fulfilled with an updated dav.Calendar object once sync is complete.
`
@param {dav.Calendar} calendar the calendar to fetch changes for.
Options:
(Array.`
#### dav.syncCaldavAccount(account, options)
Fetch changes from the remote server to the account's calendars. Returns a Promise which will be fulfilled with an updated dav.Account object once sync is complete.
`
@param {dav.Account} account the calendar account to sync.
Options:
(dav.Sandbox) sandbox - optional request sandbox.
(dav.Transport) xhr - request sender.
`
$3
#### dav.createCard(addressBook, options)
Create a vcard object on the parameter address book. Returns a Promise which will be fulfilled when the vcard has been created.
`
@param {dav.AddressBook} addressBook the address book to put the object on.
Options:
(String) data - VCARD object.
(String) filename - name for the vcard vcf file.
(dav.Sandbox) sandbox - optional request sandbox.
(dav.Transport) xhr - request sender.
`
#### dav.updateCard(card, options)
Persist updates to the parameter vcard object to the server. Returns a Promise which will be fulfilled when the vcard has been updated.
`
@param {dav.VCard} card updated vcard object.
Options:
(dav.Sandbox) sandbox - optional request sandbox.
(dav.Transport) xhr - request sender.
`
#### dav.deleteCard(card, options)
Delete the parameter vcard object on the server. Returns a Promise which will be fulfilled when the vcard has been deleted.
`
@param {dav.VCard} card target vcard object.
Options:
(dav.Sandbox) sandbox - optional request sandbox.
(dav.Transport) xhr - request sender.
`
#### dav.syncAddressBook(addressBook, options)
Fetch changes from the remote server to the parameter address books. Returns a Promise which will be fulfilled with an updated dav.AddressBook object once sync is complete.
`
@param {dav.AddressBook} addressBook the address book to fetch changes for.
Options:
(dav.Sandbox) sandbox - optional request sandbox.
(String) syncMethod - either 'basic' or 'webdav'. If unspecified, will
try to do webdav sync and failover to basic sync if rfc 6578 is not
supported by the server.
(dav.Transport) xhr - request sender.
`
#### dav.syncCarddavAccount(account, options)
Fetch changes from the remote server to the account's address books. Returns a Promise which will be fulfilled with an updated dav.Account object once sync is complete.
`
@param {dav.Account} account the address book account to sync.
Options:
(dav.Sandbox) sandbox - optional request sandbox.
(dav.Transport) xhr - request sender.
`
$3
#### dav.Sandbox()
Create a request sandbox. There is also a deprecated interface
dav.createSandbox(). Add requests to the sandbox like so:
`js
var sandbox = new dav.Sandbox();
// sandbox instanceof Sandbox
dav.createAccount({
username: 'Yoshi',
password: 'babybowsersoscaryomg',
server: 'https://caldav.yoshisstory.com',
sandbox: sandbox // <- Insert sandbox here!
})
.then(function(calendars) {
// etc, etc.
});
`
And abort sandboxed requests as a group with sandbox.abort().
$3
#### dav.transport.Basic(credentials)
Create a new dav.transport.Basic object. This sends dav requests using http basic authentication.
`
@param {dav.Credentials} credentials user authorization.
`
##### dav.transport.Basic.send(request, options)
`
@param {dav.Request} request object with request info.
@return {Promise} a promise that will be resolved with an xhr request after its readyState is 4 or the result of applying an optional request transformResponse function to the xhr object after its readyState is 4.
Options:
(dav.Sandbox) sandbox - optional request sandbox.
`
#### dav.transport.OAuth2(credentials)
Create a new dav.transport.OAuth2 object. This sends dav requests authorized via rfc 6749 oauth2.
`
@param {dav.Credentials} credentials user authorization.
`
##### dav.transport.OAuth2.send(request, options)
`
@param {dav.Request} request object with request info.
@return {Promise} a promise that will be resolved with an xhr request after its readyState is 4 or the result of applying an optional request transformResponse function to the xhr object after its readyState is 4.
Options:
(dav.Sandbox) sandbox - optional request sandbox.
`
$3
#### dav.request.addressBookQuery(options)
`
Options:
(String) depth - optional value for Depth header.
(Array.`
#### dav.request.basic(options)
`
Options:
(String) data - put request body.
(String) method - http method.
(String) etag - cached calendar object etag.
`
#### dav.request.calendarQuery(options)
`
Options:
(String) depth - optional value for Depth header.
(Array.`
#### dav.request.propfind(options)
`
Options:
(String) depth - optional value for Depth header.
(Array.`
#### dav.request.syncCollection(options)
`
Options:
(String) depth - option value for Depth header.
(Array.`
$3
#### dav.Client(xhr, options)
Create a new dav.Client object. The client interface allows consumers to set their credentials and transport once and then make authorized requests without passing them to each request. Each of the other, public API methods should be available on dav.Client objects.
`
@param {dav.Transport} xhr - request sender.
Options:
(String) baseUrl - root url to resolve relative request urls with.
`
##### dav.Client.send(req, options)
Send a request using this client's transport (and perhaps baseUrl).
`
@param {dav.request.Request} req - dav request.
@return {Promise} a promise that will be resolved with an xhr request after its readyState is 4 or the result of applying an optional request transformResponse function to the xhr object after its readyState is 4.
Options:
(dav.Sandbox) sandbox - optional request sandbox.
(String) url - relative url for request.
`
$3
#### dav.ns
Object that holds various xml namespace constants.
$3
`js
var dav = require('dav');
var xhr = new dav.transport.Basic(
new dav.Credentials({
username: 'xxx',
password: 'xxx'
})
);
dav.createAccount({ server: 'http://dav.example.com', xhr: xhr })
.then(function(account) {
// account instanceof dav.Account
account.calendars.forEach(function(calendar) {
console.log('Found calendar named ' + calendar.displayName);
// etc.
});
});
// Or, using the dav.Client interface:
var client = new dav.Client(xhr);
// No transport arg
client.createAccount({
server: 'http://dav.example.com',
accountType: 'carddav'
})
.then(function(account) {
account.addressBooks.forEach(function(addressBook) {
console.log('Found address book name ' + addressBook.displayName);
// etc.
});
});
`
#### Using the lower-level webdav request api
_Caution_: The lower-level request api is undergoing some _major_ reworking with frequent changes which will break consumers upgrading from earlier versions. If you're looking for a stable api and can live with the higher-level CalDAV and/or CardDAV abstractions, I _strongly_ recommend those since that api is largely stable.
`
var dav = require('dav');
var client = new dav.Client(
new dav.transport.Basic(
new dav.Credentials({
username: 'xxx',
password: 'xxx'
})
),
{
baseUrl: 'https://mail.mozilla.com'
}
);
var req = dav.request.basic({
method: 'PUT',
data: 'BEGIN:VCALENDAR\nEND:VCALENDAR',
etag: '12345'
});
// req instanceof dav.Request
client.send(req, '/calendars/123.ics')
.then(function(response) {
// response instanceof XMLHttpRequest
});
`
Or perhaps without the client:
`
var dav = require('dav');
var xhr = new dav.transport.Basic(
new dav.Credentials({
username: 'xxx',
password: 'xxx'
})
);
// xhr instanceof dav.Transport
var req = dav.request.basic({
method: 'PUT',
data: 'BEGIN:VCALENDAR\nEND:VCALENDAR',
etag: '12345'
});
// req instanceof dav.Request
xhr.send(req, 'https://mail.mozilla.com/calendars/123.ics')
.then(function(response) {
// response instanceof XMLHttpRequest
});
`
For more example usages, check out the suite of integration tests.
Debugging
As of version 1.8.0, dav can tell you a lot of potentially useful things if you set the DEBUG environment variable to dav:*.
You might filter them by setting DEBUG=dav:contacts, DEBUG=dav:xmlhttprequest`, etc.