-
Notifications
You must be signed in to change notification settings - Fork 21
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Update README.md to include bookable event and re-structure functions
- Loading branch information
1 parent
2386607
commit 0dc6663
Showing
1 changed file
with
126 additions
and
95 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,6 +1,6 @@ | ||
| A simple wrapper for the [Cronofy API](https://www.cronofy.com/developers/api/). | ||
|
|
||
| ## Basic Usage | ||
| # Basic Usage | ||
|
|
||
| The APIs should be one to one with the all of the current methods in [Cronofy's documentation](https://www.cronofy.com/developers/api/). The general pattern is that each method takes an options object and an optional callback. If a callback is not passed in as the second argument the function will act as a promise. | ||
|
|
||
|
|
@@ -38,10 +38,48 @@ cronofyClient.requestAccessToken(options, function(err, response){ | |
|
|
||
| The cronofy client object can be initialized with client and token details. These details will be automatically added to each call that they are needed for, but these values can be replaced by any specified in the method's `options` object. | ||
|
|
||
| `data_center` is the two-letter designation for the data center you want to operate against - for example `de` for Germany, or `au` for Australia. When omitted, this defaults to the US data center. You can find this value on your app's dashboard under `SDK identifier`. | ||
| `data_center` is the two-letter designation for the data center you want to operate against - for example `de` for Germany, or `au` for Australia. When omitted, this defaults to the US data center. You can find this value on your app's dashboard under `SDK identifier`. | ||
|
|
||
| ## Functions available | ||
| # Functions available | ||
|
|
||
| ### requestAccessToken(options, callback) | ||
|
|
||
| Takes options object and an optional callback, either returning a promise for, or calling the provided callback with an object containing an access and refresh token for you to use with future requests. | ||
|
|
||
| ### refreshAccessToken(options, callback) | ||
|
|
||
| Takes an optional callback, either returning a promise for, or calling the provided callback with the new refresh and access token information. | ||
|
|
||
| #### Options Object | ||
|
|
||
| - **code** - required - The short-lived, single-use code issued to you when the user authorized your access to their account as part of an Authorization Request. | ||
| - **redirect_uri** - required - The same HTTP or HTTPS URI you passed when requesting the user's authorization. | ||
|
|
||
| ### revokeAuthorization(callback) | ||
|
|
||
| Takes an optional callback, either returning a promise for, or calling the provided callback with an empty object in the success case. | ||
|
|
||
| ### elevatedPermissions(options, callback) | ||
|
|
||
| Takes options object and an optional callback, either returning a promise for, or calling the provided callback with an object containing a permissions URL with a token | ||
|
|
||
| #### Options Object | ||
|
|
||
| - **permissions** - required - An array of objects with a calendar_id and permission_level | ||
| - **redirect_uri** - required - Url to redirect the user to in order to grant or reject requested access | ||
|
|
||
| ### authorizeWithServiceAccount(options, callback) | ||
|
|
||
| Takes options object and an optional callback, either returning a promise for, or calling the provided callback with an empty object in the success case. | ||
|
|
||
| #### Options Object | ||
|
|
||
| - **email** - required - The email of the user to be authorized | ||
| - **scope** - required - The scopes to authorize for the user | ||
| - **callback_url** - required - The URL to return to after the authorization | ||
|
|
||
|
|
||
| ## Account functions | ||
| ### accountInformation(callback) | ||
|
|
||
| Takes an optional callback, either returning a promise for, or calling the provided callback with an object containing the account information. | ||
|
|
@@ -59,6 +97,12 @@ Takes an optional callback, either returning a promise for, or calling the provi | |
| } | ||
| ``` | ||
|
|
||
| ### profileInformation(callback) | ||
|
|
||
| Takes an optional callback, either returning a promise for, or calling the provided callback with an array of the user's calendar profiles. | ||
|
|
||
| ## Events functions | ||
|
|
||
| ### createEvent(options, callback) | ||
|
|
||
| Takes options object and an optional callback, either returning a promise for, or calling the provided callback with an empty object in the success case. | ||
|
|
@@ -74,6 +118,17 @@ Takes options object and an optional callback, either returning a promise for, o | |
| - **end** - required - The end time of the event as an ISO string. | ||
| - **location** - An object containing a single key of 'description', whos value is a string of the event location. | ||
|
|
||
| ### readEvents(options, callback) | ||
|
|
||
| Takes options object and an optional callback, either returning a promise for, or calling the provided callback with an array of the user's events accross all calendars. | ||
|
|
||
| #### Options Object | ||
|
|
||
| - **from** - required - the start date as an ISO string. | ||
| - **to** - required - the end date as an ISO string. | ||
| - **tzid** - the timezone id for the query. | ||
| - **next_page** - url for the next page. This will still apply other options to the request. | ||
|
|
||
| ### deleteEvent(options, callback) | ||
|
|
||
| Returns an empty string/promise for an empty string on success. | ||
|
|
@@ -101,41 +156,11 @@ Takes options object and an optional callback, either returning a promise for, o | |
| - **from** - required - the state date/time as an ISO string. | ||
| - **to** - required - the end date/time as an ISO string. | ||
|
|
||
| ### listCalendars(callback) | ||
|
|
||
| Takes an optional callback, either returning a promise for, or calling the provided callback with a list of calendars for the user. | ||
|
|
||
| ### profileInformation(callback) | ||
|
|
||
| Takes an optional callback, either returning a promise for, or calling the provided callback with an array of the user's calendar profiles. | ||
|
|
||
| ### readEvents(options, callback) | ||
|
|
||
| Takes options object and an optional callback, either returning a promise for, or calling the provided callback with an array of the user's events accross all calendars. | ||
|
|
||
| #### Options Object | ||
|
|
||
| - **from** - required - the start date as an ISO string. | ||
| - **to** - required - the end date as an ISO string. | ||
| - **tzid** - the timezone id for the query. | ||
| - **next_page** - url for the next page. This will still apply other options to the request. | ||
|
|
||
| ### refreshAccessToken(options, callback) | ||
|
|
||
| Takes an optional callback, either returning a promise for, or calling the provided callback with the new refresh and access token information. | ||
|
|
||
| ### requestAccessToken(options, callback) | ||
|
|
||
| Takes options object and an optional callback, either returning a promise for, or calling the provided callback with an object containing an access and refresh token for you to use with future requests. | ||
|
|
||
| #### Options Object | ||
|
|
||
| - **code** - required - The short-lived, single-use code issued to you when the user authorized your access to their account as part of an Authorization Request. | ||
| - **redirect_uri** - required - The same HTTP or HTTPS URI you passed when requesting the user's authorization. | ||
| ### updateExternalEvent(options, callback) | ||
|
|
||
| ### revokeAuthorization(callback) | ||
| Allows the editing of external events on accounts which have granted [Extended Permissions](https://docs.cronofy.com/developers/api/authorization/extended-permissions/) | ||
|
|
||
| Takes an optional callback, either returning a promise for, or calling the provided callback with an empty object in the success case. | ||
| See full details in the [Update External Event documentation](https://docs.cronofy.com/developers/api/events/edit-external-events/). | ||
|
|
||
| ### deleteExternalEvent(options, callback) | ||
|
|
||
|
|
@@ -146,26 +171,13 @@ Takes options object and an optional callback, either returning a promise for, o | |
| - **calendar_id** - required - the id of the calendar that the event will be deleted from. | ||
| - **event_uid** - required - An id for the external event you want to delete. | ||
|
|
||
| ### elevatedPermissions(options, callback) | ||
|
|
||
| Takes options object and an optional callback, either returning a promise for, or calling the provided callback with an object containing a permissions URL with a token | ||
|
|
||
| #### Options Object | ||
|
|
||
| - **permissions** - required - An array of objects with a calendar_id and permission_level | ||
| - **redirect_uri** - required - Url to redirect the user to in order to grant or reject requested access | ||
|
|
||
| ### authorizeWithServiceAccount(options, callback) | ||
|
|
||
| Takes options object and an optional callback, either returning a promise for, or calling the provided callback with an empty object in the success case. | ||
| ## Calendar functions | ||
|
|
||
| #### Options Object | ||
| ### listCalendars(callback) | ||
|
|
||
| - **email** - required - The email of the user to be authorized | ||
| - **scope** - required - The scopes to authorize for the user | ||
| - **callback_url** - required - The URL to return to after the authorization | ||
| Takes an optional callback, either returning a promise for, or calling the provided callback with a list of calendars for the user. | ||
|
|
||
| ## Push Notification Methods | ||
| ## Push Notification functions | ||
|
|
||
| ### createNotificationChannel(options, callback) | ||
|
|
||
|
|
@@ -187,29 +199,7 @@ Takes options object and an optional callback, either returning a promise for, o | |
|
|
||
| Takes an optional callback, either returning a promise for, or calling the provided callback with a list of notification channels. | ||
|
|
||
| ### addToCalendar(options, callback) | ||
|
|
||
| Takes options object and an optional callback, either returning a promise for, or calling the provided callback with a URL to redirect the user towards | ||
|
|
||
| #### Options Object | ||
|
|
||
| - **client_id** - required - The client ID. | ||
| - **client_secret** - required - The client secret. | ||
| - **oauth** - required - The OAuth information for the end-user to connect their calendar. | ||
| - **redirect_uri** - required - The URL to send the end-user to after completing the Add To Calendar flow. | ||
| - **scope** - required - The scope to request from the end-user during the oauth flow. | ||
| - **event** - required - The event to create in the user's calendar. | ||
| - **event_id** - required - The event's ID. | ||
| - **summary** - required - The event's summary. | ||
| - **start** - required - The event's start date. | ||
| - **end** - required - The event's end date. | ||
| - **description** - required - The event's description. | ||
| - **location** - optional - The event's location. | ||
| - **url** - optional - The event's URL. | ||
| - **reminders** - optional - The event's reminders. | ||
| - **transparency** - optional - The event's transparency. | ||
|
|
||
| ## Managed Availability methods | ||
| ## Managed Availability functions | ||
|
|
||
| ### listAvailabilityRules(options, callback) | ||
|
|
||
|
|
@@ -273,6 +263,8 @@ Provide either: | |
|
|
||
| - **delete_all** - set to `true` to bulk delete all Available Periods for the account. | ||
|
|
||
| ## Real-Time Scheduling functions | ||
|
|
||
| ### realTimeScheduling(options, callback) | ||
|
|
||
| Takes options object and an optional callback, either returning a promise or calling the provided callback with the body of the response (or error, if applicable). | ||
|
|
@@ -292,6 +284,30 @@ See full details in the [Real-Time Scheduling documentation](https://docs.cronof | |
| - **availability.start_interval** - optional - A `Duration` describing the frequency that a sequence can start on. [More details in the documentation](https://docs.cronofy.com/developers/api/scheduling/real-time-scheduling/#availability.start_interval). | ||
| - **minimum_notice** - optional - A `Duration`. No slots starting before the period described after the current time will be displayed to the user when they select slots. | ||
|
|
||
| ### addToCalendar(options, callback) | ||
|
|
||
| Takes options object and an optional callback, either returning a promise for, or calling the provided callback with a URL to redirect the user towards | ||
|
|
||
| #### Options Object | ||
|
|
||
| - **client_id** - required - The client ID. | ||
| - **client_secret** - required - The client secret. | ||
| - **oauth** - required - The OAuth information for the end-user to connect their calendar. | ||
| - **redirect_uri** - required - The URL to send the end-user to after completing the Add To Calendar flow. | ||
| - **scope** - required - The scope to request from the end-user during the oauth flow. | ||
| - **event** - required - The event to create in the user's calendar. | ||
| - **event_id** - required - The event's ID. | ||
| - **summary** - required - The event's summary. | ||
| - **start** - required - The event's start date. | ||
| - **end** - required - The event's end date. | ||
| - **description** - required - The event's description. | ||
| - **location** - optional - The event's location. | ||
| - **url** - optional - The event's URL. | ||
| - **reminders** - optional - The event's reminders. | ||
| - **transparency** - optional - The event's transparency. | ||
|
|
||
| ## Batch Request functions | ||
|
|
||
| ### batch(options, callback) | ||
|
|
||
| Takes options object and an optional callback, either returning a promise or calling the provided callback with the body of the response (or error, if applicable). | ||
|
|
@@ -305,46 +321,61 @@ See full details in the [Batch documentation](https://docs.cronofy.com/developer | |
| - **batch.relative_url** - required - A `String` for the relative URL (sometimes referred to as the path and query string) of the individual request. Maps directly from its main documentation. | ||
| - **batch.data** - required - An object containing the body parameters of the request. Maps directly from its main documentation. Note that this is an object, not a JSON-encoded string. | ||
|
|
||
| ### updateExternalEvent(options, callback) | ||
|
|
||
| Allows the editing of external events on accounts which have granted [Extended Permissions](https://docs.cronofy.com/developers/api/authorization/extended-permissions/) | ||
|
|
||
| See full details in the [Update External Event documentation](https://docs.cronofy.com/developers/api/events/edit-external-events/). | ||
|
|
||
| ## A feature I want is not in the SDK, how do I get it? | ||
|
|
||
| We add features to this SDK as they are requested, to focus on developing the Cronofy API. | ||
|
|
||
| If you're comfortable contributing support for an endpoint or attribute, then we love to receive pull requests! | ||
| Please create a PR mentioning the feature/API endpoint you’ve added and we’ll review it as soon as we can. | ||
|
|
||
| If you would like to request a feature is added by our team then please let us know by getting in touch via [[email protected]](mailto:[email protected]). | ||
|
|
||
| ## Bookable Event functions | ||
|
|
||
| ### createBookableEvent(options, callback) | ||
|
|
||
| Takes options object and an optional callback, either returning a promise or calling the provided callback with the body of the response (or error, if applicable). | ||
|
|
||
| See full details in the [Bookable Event documentation](https://docs.cronofy.com/developers/api/scheduling/bookable-events/create/). | ||
|
|
||
| #### Options Object | ||
|
|
||
| - **bookable_event_id** - required - the id of the bookable event that the event will be created. | ||
| - **start** - required - The start time for the event in UTC. | ||
| - **end** - required - The end time for the event in UTC. | ||
| - **status** - required - The status of the event, either `"confirmed"` or `"cancelled"`. | ||
| - **registration.capacity** - The maximum number of attendees that can register for the event. | ||
| - **registration.capacity** - required - The maximum number of attendees that can register for the event. | ||
|
|
||
| See full details in the [Create Bookable Event documentation](https://docs.cronofy.com/developers/api/scheduling/bookable-events/create/). | ||
|
|
||
| ### readBookableEvent(options, callback) | ||
|
|
||
| Takes options object and an optional callback, either returning a promise for, or calling the provided callback with an object representing the bookable event. | ||
|
|
||
| #### Options Object | ||
|
|
||
| - **bookable_event_id** - required - the id of the bookable event that the event will be created. | ||
| - **bookable_event_id** - required - the id of the bookable event. | ||
|
|
||
| See full details in the [Read Bookable Event documentation](https://docs.cronofy.com/developers/api/scheduling/bookable-events/read/). | ||
|
|
||
| ### upsertRegistrationBookableEvent(options, callback) | ||
|
|
||
| Takes options object and an optional callback, either returning a promise for, or calling the provided callback with an object representing the bookable event. | ||
|
|
||
| #### Options Object | ||
|
|
||
| - **bookable_event_id** - required - the id of the bookable event that the registration will be created/updated against. | ||
| - **registration_id** - required - the id of the registration that will be created/updated. | ||
| - **status** - required - the status of the registration, must be one of `"pending"`, `"accepted"`, `"tentative"`, `"declined"`, `"removed"`. | ||
| - **metadata** - optional - additional data saved against the registration, up to 10 key-value pairs. | ||
|
|
||
| See full details in the [Create or Update Registration documentation](https://docs.cronofy.com/developers/api/scheduling/bookable-events/registrations/upsert/). | ||
|
|
||
| ### deleteRegistrationBookableEvent(options, callback) | ||
|
|
||
| Takes options object and an optional callback, either returning a promise for, or calling the provided callback with an object representing the bookable event. | ||
|
|
||
| #### Options Object | ||
|
|
||
| - **bookable_event_id** - required - the id of the bookable event that the registration will be removed against. | ||
| - **registration_id** - required - the id of the registration that will be removed. | ||
|
|
||
| See full details in the [Delete Registration documentation](https://docs.cronofy.com/developers/api/scheduling/bookable-events/registrations/delete/). | ||
|
|
||
| ## A feature I want is not in the SDK, how do I get it? | ||
|
|
||
| We add features to this SDK as they are requested, to focus on developing the Cronofy API. | ||
|
|
||
| If you're comfortable contributing support for an endpoint or attribute, then we love to receive pull requests! | ||
| Please create a PR mentioning the feature/API endpoint you’ve added and we’ll review it as soon as we can. | ||
|
|
||
| If you would like to request a feature is added by our team then please let us know by getting in touch via [[email protected]](mailto:[email protected]). | ||