Coconut Open API JS SDK
Install
Using npm:
$ npm install coconut-open-api-jsUsing yarn:
$ yarn add coconut-open-api-jsOfficial Documentation
Documentation for the Open API can be found on the Developer Portal.
Usage
Answers
Methods
for(question: number)
Set an attribute to determine the identifier of the question being answer.
is(value: string)
Set an attribute to determine the actual answer's value.
Example
import { Answer } from 'coconut-open-api-js';
class Answers {
static create({ question, value }) {
return (new Answer())
.for(question)
.is(value);
}
}Appointments
Methods
add(appointment: number)
Add the currently supplied attendees to the given appointment.
at(location: number)
Set a relationship which will tell the API to use the given location identifier when creating an appointment.
attendedBy(users: number | number[])
Set a relationship which will tell the API to use the given additional user identifier when creating an appointment.
book()
Create a new appointment using the pre-set parameters.
by(user: number)
Set a relationship which will tell the API to use the given user identifier when creating an appointment.
cancel(appointment: number, attendee: number, code: string)
Cancel an appointment for a specific attendee matching the given appointment, attendee and confirmation code identifiers.
campaign(campaign: string)
Set an attribute which will tell the API to use the given string as the campaign UTM parameter when creating an appointment.
content(content: string)
Set an attribute which will tell the API to use the given string as the content UTM parameter when creating an appointment.
for(services: number | numbers[])
Set a relationship which will tell the API to use the given service identifier when creating an appointment.
get()
Find an appointment matching the pre-set matching parameters.
in(timezone: string)
Set the timezone in which the server will interpret the appointment start time as.
matching(matchers: AppointmentMatcherParameters)
Set a filter to use in order to find an existing appointment.
method(method: number)
Set a filter which will tell the API to use the given meeting method when creating an appointment.
medium(medium: string)
Set an attribute which will tell the API to use the given string as the medium UTM parameter when creating an appointment.
notify(notifications: AppointmentNotificationParameters)
Set a filter to determine who should be notified when booking an appointment.
reschedule(appointment: number, code: string)
Reschedule an appointment matching the given appointment identifier using the pre-set start parameter.
starting(start: string)
Set an attribute which will tell the API to use the given start date time string as the start time of the new appointment.
source(source: string)
Set an attribute which will tell the API to use the given string as the source UTM parameter when creating an appointment.
supporting(locale: string | null)
Set a locale to use as a filter when not supplying a staff preference to ensure the best possible match when creating an appointment.
term(term: string)
Set an attribute which will tell the API to use the given string as the term UTM parameter when creating an appointment.
through(origin: number)
Set an attribute which will tell the API to use the given origin constant as the booked through value when creating an appointment.
uploads(uploadedFiles: UploadedFile[])
Attach uploaded files when creating an appointment.
via(invitation: number)
Set an attribute which will tell the API to use the given invitation identifier when creating an appointment.
with(attendees: AttendeeModel | AttendeeModel[])
Set a relationship which will tell the API to use the given attendee model(s) when creating a new appointment.
withInviteOnly(inviteOnlyResources?: boolean)
Set an attribute which will tell the API to allow invite only location, service and user to be used when creating an appointment.
withinUserCategory(userCategory: number)
Set a relationship which will tell the API to use the given user category identifier when creating an appointment.
withoutMeetingLink(skipMeetingLinkGeneration?: boolean)
Set an attribute which will tell the API to skip the meeting link generation when creating an appointment.
workflow(workflow: number)
Set a relationship which will tell the API to use the given workflow identifier when creating an appointment.
Example
import { OpenApi, Attendee, Answer, MeetingMethods, Notifications, Origins, Response } from 'coconut-open-api-js';
class Appointments {
constructor() {
this.api = new OpenApi();
}
async add(attributes) {
const {
address, appointment, campaign, city, content, country, email, file,
firstName, key, language, lastName, medium, notes, phone, question,
source, term, value,
} = attributes;
const answer = (new Answer())
.for(question)
.is(value);
const attendee = (new Attendee())
.answers(answer)
.located({ address, city, country })
.messagable()
.named(firstName, lastName)
.provided(notes)
.reachable({ phone, email })
.speaks(language);
return this.api
.appointments()
.campaign(campaign)
.content(content)
.medium(medium)
.method(MeetingMethods.AT_LOCATION)
.source(source)
.term(term)
.with(attendee)
.through(Origins.MODERN_CLIENT_VIEW)
.uploads([{ key, file }])
.notify(Notifications.ALL)
.add(appointment);
}
async book(attributes) {
const {
address, campaign, city, content, country, email, file, firstName, key,
invitation, language, lastName, location, locale, medium, notes, phone,
question, service, source, start, term, timezone, user, userCategory,
users, value, workflow,
} = attributes;
const answer = (new Answer())
.for(question)
.is(value);
const attendee = (new Attendee())
.answers(answer)
.located({ address, city, country })
.messagable()
.named(firstName, lastName)
.provided(notes)
.reachable({ phone, email })
.speaks(language);
return this.api
.appointments()
.at(location)
.attendedBy(users)
.by(user)
.for(service)
.starting(start)
.campaign(campaign)
.content(content)
.medium(medium)
.in(timezone)
.source(source)
.supporting(locale)
.term(term)
.uploads([{ key, file }])
.via(invitation)
.with(attendee)
.through(Origins.MODERN_CLIENT_VIEW)
.withInviteOnly()
.withinUserCategory(userCategory)
.withoutMeetingLink()
.workflow(workflow)
.notify(Notifications.ALL)
.book();
}
async cancel(attributes) {
const { appointment, attendee, code } = attributes;
// We can optionally submit custom form responses when cancelling
// appointments by utilizing the Response and Attendee models.
const person = (new Attendee())
.as(attendee)
.responses([
(new Response()).for(1).is('an answer'),
(new Response()).for(2).selected(1),
]);
return this.api.appointments()
.with(person)
.cancel(appointment, attendee, code);
}
async fetch({ code, id }) {
return this.api.appointments().matching({ code, id }).get();
}
async reschedule({ appointment, code, start }) {
return this.api
.appointments()
.starting(start)
.withoutMeetingLink()
.notify(Notifications.ALL)
.reschedule(appointment, code);
}
}Attendees
Methods
alias(alias: string | number)
Set the external identifier for the given attendee.
answers(answers: AnswerModel | AnswerModel[])
Set a relationship which will tell the API to use the given answer model(s) for the attendee when booking an appointment.
as(identifier: number)
Set the identifier for a given attendee.
located(details: LocatableDetailParameters)
Set certain attributes on the attendee related to location details such as address and city.
messageable()
Set a flag on the attendee which determines that they have opted to receive sms messages.
named(first: string, last: string)
Set the first and last name of the attendee.
provided(notes: string)
Set any additional details the attendee has provided when booking an appointment.
reachable(details: ReachableDetailParameters)
Set certain attributes on the attendee related to contact details such as cell phone and email.
responses(answers: ResponseModel | ResponseModel[])
Set a relationship which will tell the API to use the given response model(s) for the attendee when cancelling an appointment.
speaks(language: string)
Set the preferred locale of the attendee.
Example
import { Attendee, Answer } from 'coconut-open-api-js';
class Attendees {
static create(attributes) {
const {
address, alias, city, country, firstName, lastName,
notes, phone, email, language, question, value
} = attributes;
const answer = (new Answer()).for(question).is(value);
return (new Attendee())
.alias(alias)
.answers(answer)
.located({ address, city, country })
.messagable()
.named(firstName, lastName)
.provided(notes)
.reachable({ phone, email })
.speaks(language);
}
}Queue Appointments
Methods
at(location: number)
Set a relationship which will tell the API to use the given location identifier when creating a queue appointment.
book()
Create a new queue appointment using the pre-set parameters.
campaign(campaign: string)
Set an attribute which will tell the API to use the given string as the campaign UTM parameter when creating a queue appointment.
content(content: string)
Set an attribute which will tell the API to use the given string as the content UTM parameter when creating a queue appointment.
for(services: number | numbers[])
Set a relationship which will tell the API to use the given service identifier when creating a queue appointment.
method(method: number)
Set a filter which will tell the API to use the given meeting method when creating a queue appointment.
medium(medium: string)
Set an attribute which will tell the API to use the given string as the medium UTM parameter when creating a queue appointment.
source(source: string)
Set an attribute which will tell the API to use the given string as the source UTM parameter when creating a queue appointment.
supporting(locale: string | null)
Set a locale to use as a filter when not supplying a staff preference to ensure the best possible match when creating a queue appointment.
through(origin: number)
Set an attribute which will tell the API to use the given origin constant as the booked through value when creating a queue appointment.
with(client: ClientModel)
Set a relationship which will tell the API to use the given client model when creating a new queue appointment.
workflow(workflow: number)
Set a relationship which will tell the API to use the given workflow identifier when creating a queue appointment.
Example
import { OpenApi, Client, Answer, MeetingMethods, Origins } from 'coconut-open-api-js';
class QueueAppointments {
constructor() {
this.api = new OpenApi();
}
async book(attributes) {
const {
campaign, content, email, firstName, language,
lastName, medium, notes, phone, question, source,
value, workflow
} = attributes;
const answer = (new Answer())
.for(question)
.is(value);
const client = (new client())
.answers(answer)
.messagable()
.named(firstName, lastName)
.provided(notes)
.reachable({ phone, email })
.speaks(language);
return this.api
.queueAppointments()
.campaign(campaign)
.content(content)
.medium(medium)
.method(MeetingMethods.AT_LOCATION)
.source(source)
.term(term)
.with(client)
.workflow(workflow)
.through(Origins.MODERN_CLIENT_VIEW)
.book();
}Clients
Methods
answers(answers: AnswerModel | AnswerModel[])
Set a relationship which will tell the API to use the given answer model(s) for the client when booking an appointment.
messageable()
Set a flag on the client which determines that they have opted to receive sms messages.
named(first: string, last: string)
Set the first and last name of the client.
provided(notes: string)
Set any additional details the client has provided when booking an appointment.
reachable(details: ReachableDetailParameters)
Set certain attributes on the client related to contact details such as cell phone and email.
speaks(language: string)
Set the preferred locale of the client.
Example
import { Client, Answer } from 'coconut-open-api-js';
class Clients {
static create(attributes) {
const {
firstName, lastName,
notes, phone, email, language, question, value
} = attributes;
const answer = (new Answer()).for(question).is(value);
return (new Client())
.answers(answer)
.messagable()
.named(firstName, lastName)
.provided(notes)
.reachable({ phone, email })
.speaks(language);
}
}Forms
Methods
cancellations()
Set a filter which will tell the API to return only cancellation forms.
get()
Send the API request using the pre-set filters.
on(page: number)
Set the page offset which you want to view.
sortBy(sortable: string)
Set a sorting string to determine how the returned results are sorted.
take(limit: number)
Set the limit which you want returned.
Example
import { OpenApi } from 'coconut-open-api-js';
class Forms {
constructor() {
this.api = new OpenApi();
}
async get({ limit, page, sortable }) {
return await this.api
.forms()
.cancellations()
.on(page)
.sortBy(sortable)
.take(limit)
.get()
}
}Locations
Methods
assigned(assigned: boolean = true)
Set a filter which will tell the API to return locations that have public user and service assignments.
containing(user: number | string)
Set a filter which will tell the API to return locations where the supplied user identifier is assigned.
details(identifier: string)
Retrieve a given location's details based on the given identifier.
get()
Send the API request using the pre-set filters.
invitable()
Set a filter which will tell the API to return locations that are specifically invite only.
located(details: LocatableLocationParameters)
Set certain filters which will tell the API to return locations that match the locatable details you provide.
on(page: number)
Set the page offset which you want to view.
physical()
Set a filter which will tell the API to return only non-virtual locations.
providing(services: number | number[] | string | string[])
Set a filter which will tell the API to return locations where the supplied service identifier(s) is / are assigned.
sortBy(sortable: string)
Set a sorting string to determine how the returned results are sorted.
suggest(query: string)
Retrieve a set of location suggestions based on the given query.
supporting(method: number)
Set a filter which will tell the API to return locations that are supported by the given meeting method.
take(limit: number)
Set the limit which you want returned.
through(resource: string)
Set a filter which will tell the API which resource the request comes from. Currently, only 'client_view' is supported.
virtual()
Set a filter which will tell the API to return only virtual locations.
withInviteOnly(inviteOnlyResources?: boolean)
Set an attribute which will tell the API to allow locations that are invite only or have invite only services or users assigned to them.
withinUserCategory(userCategory: number | string)
Set a filter which will tell the API to return locations where users assigned to it are within the category matching the provided identifier.
Example
import { OpenApi } from 'coconut-open-api-js';
class Locations {
constructor() {
this.api = new OpenApi();
}
async details(identifier) {
return await this.api.details(identifier);
}
async get({ page, limit, method, resource, services, sortable, user, userCategory }) {
return await this.api
.locations()
.assigned()
.containing(user)
.invitable()
.providing(services)
.physical()
.supporting(method)
.withInviteOnly()
.withinUserCategory(userCategory)
.sortBy(sortable)
.through(resource)
.on(page)
.take(limit)
.get();
}
async suggestions(query) {
return await this.api.suggest(query);
}
}Preferences
Methods
between(start: string, end: string)
Set the attributes to determine the start and end time of the wait list request preference.
next()
Set an attribute to say that the preference is for the next available opening.
on(day: number)
Set the attribute to determine the preferred day of the wait list request preference and that it should only be for the certain supplied days.
Example
import { Preference } from 'coconut-open-api-js';
class Preferences {
static create({ day, start, end }) {
return (new Preference()).between(start, end).on(day);
}
}Questions
Methods
for(services: number | number[] | string | string[])
Set a filter which will tell the API to return questions which are specifically assigned to the given service identifier(s).
get()
Send the API request using the pre-set filters.
on(page: number)
Set the page offset which you want to view.
sortBy(sortable: string)
Set a sorting string to determine how the returned results are sorted.
take(limit: number)
Set the limit which you want returned.
Example
import { OpenApi } from 'coconut-open-api-js';
class Questions {
constructor() {
this.api = new OpenApi();
}
async get({ limit, page, services, sortable }) {
return await this.api
.questions()
.for(services)
.on(page)
.sortBy(sortable)
.take(limit)
.get()
}
}Responses
Methods
for(question: number)
Set an attribute to determine the identifier of the question being answer.
is(value: string)
Set an attribute to determine the actual answer's value.
Example
import { Response } from 'coconut-open-api-js';
class Responses {
static create({ question, value }) {
return (new Response())
.for(question)
.is(value);
}
static select({ question, option }) {
return (new Response())
.for(question)
.selected(option);
}
}Services
Methods
assigned(assigned: boolean = true)
Set a filter which will tell the API to return services that have public user and location assignments.
at(location: number | string)
Set a filter which will tell the API to return services that are provided at the location matching the provided identifier.
by(user: number | string)
Set a filter which will tell the API to return services that are provided by the user matching the provided identifier.
get()
Send the API request using the pre-set filters.
group()
Set a filter which will tell the API to return only group type services.
in(category: number | string)
Set a filter which will tell the API to return services that match the given category identifier.
individual()
Set a filter which will tell the API to return only individual type services.
invitable()
Set a filter which will tell the API to return services that are specifically invite only.
located(details: LocatableServiceParameters)
Set certain filters which will tell the API to return services that match the locatable details you provide.
on(page: number)
Set the page offset which you want to view.
sortBy(sortable: string)
Set a sorting string to determine how the returned results are sorted.
supporting(method: number)
Set a filter which will tell the API to return services that are supported by the given meeting method.
take(limit: number)
Set the limit which you want returned.
through(resource: string)
Set a filter which will tell the API which resource the request comes from. Currently, only 'client_view' is supported.
withInviteOnly(inviteOnlyResources?: boolean)
Set an attribute which will tell the API to allow services that are invite only or have invite only locations or users assigned to them.
withinLocationCategory(locationCategory: number | string)
Set a filter which will tell the API to return users that are specifically for users within the location category matching the provided identifier.
withinUserCategory(userCategory: number | string)
Set a filter which will tell the API to return services that are provided by user within the category matching the provided identifier.
Example
import { OpenApi } from 'coconut-open-api-js';
class Services {
constructor() {
this.api = new OpenApi();
}
async get({ category, limit, location, locationCategory, method, page, region, resource, sortable, user, userCategory }) {
return await this.api
.services()
.assigned()
.at(location)
.by(user)
.in(category)
.invitable()
.located({ region })
.supporting(method)
.through(resource)
.withInviteOnly()
.withinLocationCategory(locationCategory)
.withinUserCategory(userCategory)
.on(page)
.sortBy(sortable)
.take(limit)
.get()
}
}Settings
Methods
get()
Send the API request.
Example
import { OpenApi } from 'coconut-open-api-js';
class Settings {
constructor() {
this.api = new OpenApi();
}
async get() {
return await this.api.settings().get();
}
}Time Slots
Methods
at(location: number)
Set a filter which will tell the API to return time slots at the location matching the provided identifier.
attendedBy(users: number | number[])
Set a filter which will tell the API to return time slots that match availability of the additional user matching the provided identifier.
between(start: string, end: string)
Set a filter which will tell the API to return time slots between a given start and end date time string.
by(user: number)
Set a filter which will tell the API to return time slots that are specifically for the user matching the provided identifier.
excluding(exclusion: number)
Set a filter which will tell the API to exclude a particular appointment identifier when generating availability.
for(services: number | number[])
Set a filter which will tell the API to return time slots that are specifically for the service(s) matching the provided identifier(s).
get()
Send the API request using the pre-set filters.
google(token: string)
Set a filter which will tell the API to return time slots that are not conflicting with events associated with the Google access token.
in(timezone: string)
Set a filter which will tell the API to return time slots in the given timezone.
supporting(locales: string[])
Set a filter which will tell the API to return time slots for users that support the given locales.
visibility(visibility: number)
Set a filter which will tell the API whether to return time slots belonging to all resources or just public resources.
withInviteOnly(inviteOnlyResources?: boolean)
Set an attribute which will tell the API to return time slots belonging to public and invite only resources.
withinLocationCategory(locationCategory: number | string)
Set a filter which will tell the API to return users that are specifically for users within the location category matching the provided identifier.
withinUserCategory(userCategory: number)
Set a filter which will tell the API to return time slots that are specifically for users within the category matching the provided identifier.
Example
import { OpenApi, Visibilities } from 'coconut-open-api-js';
class TimeSlots {
constructor() {
this.api = new OpenApi();
}
async get({ appointment, end, location, locationCategory, service, start, token, user, userCategory, users }) {
return await this.api
.slots()
.at(location)
.attendedBy(users)
.by(user)
.for(service)
.google(token)
.between(start, end)
.excluding(appointment)
.in('America/Chicago')
.supporting(['en', 'fr', 'es'])
.visibility(Visibilities.ALL)
.withInviteOnly()
.withinLocationCategory(locationCategory)
.withinUserCategory(userCategory)
.get()
}
}Users
Methods
assigned(assigned: boolean = true)
Set a filter which will tell the API to return users that have public location and service assignment.
at(location: number | string)
Set a filter which will tell the API to return users that are assigned at the location matching the provided identifier.
find(user: number | string)
Set a filter which will tell the API to return a user matching the provided identifier.
get()
Send the API request using the pre-set filters.
located(details: LocatableUserParameters)
Set certain filters which will tell the API to return users that match the locatable details you provide.
on(page: number)
Set the page offset which you want to view.
performing(services: number | number[] | string | string[])
Set a filter which will tell the API to return users that are assigned to the service(s) matching the provided identifier(s).
sortBy(sortable: string)
Set a sorting string to determine how the returned results are sorted.
supporting(method: number)
Set a filter which will tell the API to return users that support the given meeting method.
take(limit: number)
Set the limit which you want returned.
through(resource: string)
Set a filter which will tell the API which resource the request comes from. Currently, only 'client_view' is supported.
withInviteOnly(inviteOnlyResources?: boolean)
Set an attribute which will tell the API to allow users that are invite only or have invite only locations or services assigned to them.
withinLocationCategory(locationCategory?: number | string)
Set a filter which will tell the API to return users that are specifically for users within the location category matching the provided identifier.
withinUserCategory(userCategory?: number | string)
Set a filter which will tell the API to return users that are specifically for users within the user category matching the provided identifier.
Example
import { OpenApi } from 'coconut-open-api-js';
class Users {
constructor() {
this.api = new OpenApi();
}
async get({ limit, location, locationCategory, method, page, region, resource, services, sortable, userCategory }) {
return await this.api
.users()
.assigned()
.at(location)
.located({ region })
.performing(services)
.supporting(method)
.through(resource)
.withInviteOnly()
.withinLocationCategory(locationCategory)
.withinUserCategory(userCategory)
.on(page)
.sortBy(sortable)
.take(limit)
.get();
}
}Wait Lists
Methods
add()
Create a new wait list request using the pre-set parameters.
at(location: number | string)
Set a relationship which will tell the API to use the given location identifier when creating or updating a wait list request.
belonging(client: number | string)
Set a parameter which will tell the API to use the given client identifier when looking for an existing wait list request.
find(list: number | string)
Find an existing wait list request matching the given identifier.
for(attendee: AttendeeModel)
Set a relationship which will tell the API to use the given attendee model when creating or updating a wait list request.
include(includes: string)
Set an inclusion parameter to include other relationships when fetching an existing wait list request.
prefers(preferences: PreferenceModel | PreferenceModel[])
Set a relationship which will tell the API to use the given preference model(s) when creating or updating a wait list request.
provided(notes: string)
Set an attribute which will tell the API to use the given notes as additional details when creating or updating a wait list request.
remove(list: number | string)
Remove a pre-set client's wait list request that matches the given identifier.
seeking(service: number | string)
Set a relationship which will tell the API to use the service identifier when creating or updating a wait list request.
update(list: number | string)
Update the wait list request matching the given identifier with pre-set attributes / relationships.
with(user: number | string)
Set a relationship which will tell the API to use the user identifier when creating or updating a wait list request.
Example
import { OpenApi, Attendee, Preference } from 'coconut-open-api-js';
class WaitLists {
constructor() {
this.api = new OpenApi();
}
async add({ firstName, lastName, email, day, start, end, location, service, user, notes }) {
const attendee = (new Attendee()).named({ firstName, lastName }).reachable({ email });
const preference = (new Preference()).on(day).between(start, end);
return this.api
.lists()
.for(attendee)
.at(location)
.seeking(service)
.with(user)
.provided(notes)
.prefers(preference)
.add();
}
async find({ client, inclusions, list }) {
return this.api
.lists()
.belonging(client)
.include(inclusions)
.find(list);
}
async remove({ client, list }) {
return this.api.lists().belonging(client).remove(list);
}
async update({ client, list, notes, user }) {
const preference = (new Preference()).next();
return this.api
.lists()
.belonging(client)
.with(user)
.prefers(preference)
.provided(notes)
.update(list);
}
}Wait Times
Methods
at(location: number | string)
Set a relationship which will tell the API to use the given location identifier when fetching wait times.
get()
Find wait times matching the pre-set matching parameters.
on(page: number)
Set the page offset which you want to view.
take(limit: number)
Set the limit which you want returned.
Example
import { OpenApi } from 'coconut-open-api-js';
class WaitTimes {
constructor() {
this.api = new OpenApi();
}
async all() {
return this.api.waitTimes().get();
}
async find({ location }) {
return this.api.waitTimes().at(location).get();
}
}Change log
Please see CHANGELOG for more information on what has changed recently.
Testing
$ yarn run testLicense
The MIT License (MIT). Please see License File for more information.