@goodtok/sdk

sdk

SDK for Goodtok Server

• Installation
• APIs

Installation

$ npm install --save @goodtok/sdk

APIs

• Customers
• Users
• Workspaces
• Tokens

Customers ⇐ AbstractBaseClient

Use the Goodtok Customers capability to retrieve and manage customers. Ensure the Goodtok API Server is running for the Customers API to function.

Kind: global class
Extends: AbstractBaseClient
See: module:sdk:Client

• Customers ⇐ AbstractBaseClient
  • new Customers(client)
  • .getCustomerById(request) ⇒ Promise.<Customer>
  • .getOrdersByCustomerId(request) ⇒ Promise.<Array.<Order>>
  • .getCustomerInDefaultWorkspace(id) ⇒ Promise.<Customer>

new Customers(client)

Constructs a new Customers API object.

Param	Type	Description
client	Client	Object containing the client configuration

Example

const SDK = require("@goodtok/sdk");

async function getCustomer() {
  const client = new SDK.Client({ workspace: "myworkspace" });
  await client.login("goodtok", "mysecretpassword");

  const customers = new SDK.Customers(client);
  const id = "5f9d7a3a-2b2b-4b7a-9b9b-8e9d9d9d9d9d";
  const customer = await customers.getCustomerById(id);

  console.log(customer);
}

getCustomer().catch(console.error);

customers.getCustomerById(request) ⇒ Promise.<Customer>

Retrieves a customer for a workspace by customer ID.

Kind: instance method of Customers
Returns: Promise.<Customer> - A promise resolving to the customer
Throws:

• Will throw an error if the customer is not found

Param	Type	Description
request	GetCustomerRequest	Request object containing the customer ID and workspace ID
request.workspaceId	string	The workspace ID
request.customerId	string	The customer ID

Example

const request = {
  workspaceId: "452b1b1b-1b1b-1b1b-1b1b-1b1b1b1b1b1b",
  customerId: "5f9d7a3a-2b2b-4b7a-9b9b-8e9d9d9d9d9d"
};

customers.getCustomer(request)
  .then(console.log)
  .catch(console.error); // handle any errors

customers.getOrdersByCustomerId(request) ⇒ Promise.<Array.<Order>>

Retrieves a list of orders for a customer by customer ID.

Kind: instance method of Customers
Returns: Promise.<Array.<Order>> - A promise resolving to the list of orders

Param	Type	Description
request	GetOrdersByCustomerIdRequest	Request object containing the customer ID and workspace ID
request.workspaceId	string	The workspace ID
request.customerId	string	The customer ID

Example

const request = {
  workspaceId: "452b1b1b-1b1b-1b1b-1b1b-1b1b1b1b1b1b",
  customerId: "5f9d7a3a-2b2b-4b7a-9b9b-8e9d9d9d9d9d"
};

customers.getOrdersByCustomerId(request)
 .then(console.log)
 .catch(console.error); // handle any errors

customers.getCustomerInDefaultWorkspace(id) ⇒ Promise.<Customer>

Retrieves a customer by ID in the default workspace.

Kind: instance method of Customers
Returns: Promise.<Customer> - A promise resolving to the customer
Throws:

• Will throw an error if the customer is not found

Param	Type	Description
id	string	The customer ID

Example

const id = "5f9d7a3a-2b2b-4b7a-9b9b-8e9d9d9d9d9d";
customers.getCustomerInDefaultWorkspace(id)
  .then(console.log)
  .catch(console.error); // handle any errors

Queues ⇐ AbstractBaseClient

Use the Goodtok Queues capability to retrieve and manage queues. Ensure the Goodtok API Server is running for the Queues API to function.

Kind: global class
Extends: AbstractBaseClient
See: module:sdk:Client

• Queues ⇐ AbstractBaseClient
  • new Queues(client)
  • .getDefaultWorkspaceQueue() ⇒ Promise.<GetQueueResponse>
  • .getQueueByWorkspaceId(id) ⇒ Promise.<Workspace>
  • .watchQueue(id, callback)
  • .updateQueueEntryStatus(request) ⇒ Promise.<void>
  • .joinQueue(request) ⇒ Promise.<void>

new Queues(client)

Constructs a new Queues API object.

Param	Type	Description
client	Client	Object containing the client configuration

Example

const SDK = require("@goodtok/sdk");

async function getWorkspace() {
  const client = new SDK.Client({ workspace: "myworkspace" });
  await client.login("goodtok", "mysecretpassword");

  const workspaceId = "g-7b7c46fb05";

  const queues = new SDK.Queues(client);
  const queue = await workspaces.getQueueByWorkspaceId(workspaceId);

  console.log(workspace);
}

getWorkspace().catch(console.error);

queues.getDefaultWorkspaceQueue() ⇒ Promise.<GetQueueResponse>

Retrieves the queue for the default workspace.

Kind: instance method of Queues
Returns: Promise.<GetQueueResponse> - A promise resolving to the queue
Example

workspaces.getDefaultWorkspaceQueue()
  .then(console.log)
  .catch(console.error); // handle any errors

queues.getQueueByWorkspaceId(id) ⇒ Promise.<Workspace>

Retrieves the queue for a workspace by its ID.

Kind: instance method of Queues
Returns: Promise.<Workspace> - A promise resolving to an object containing an array of queue entries

Param	Type	Description
id	string	The workspace ID

Example

const id = "g-7b7c46fb05";

queues.getQueueByWorkspaceId(id)
  .then(console.log)
  .catch(console.error); // handle any errors

queues.watchQueue(id, callback)

Registers a callback for real-time updates on queue entries within a workspace.

Kind: instance method of Queues

Param	Type	Description
id	string	The ID of the workspace
callback	function	The callback to be invoked when a queue entry updates

Example

const id = "4f9d5a3a-362b-7b7a-34gb-4e94969d7d2d";

queues.watchQueue(id, (err, data) => {
  if (err) {
   console.error(err);
   return;
  }

  console.log(data);
});

queues.updateQueueEntryStatus(request) ⇒ Promise.<void>

Updates the status of a queue entry.

Kind: instance method of Queues
Returns: Promise.<void> - A promise resolving to void

Param	Type	Description
request	UpdateQueueEntryStatusRequest	The request object
request.workspaceId	string	The workspace ID
request.customerId	string	The customer ID to update the queue entry for
request.status	string	The status to update the queue entry to

Example

const request = {
 workspaceId: "g-7b7c46fb05",
 customerId: "4f9d5a3a-362b-7b7a-34gb-4e94969d7d2d",
 status: "DEQUEUED"
};

queues.updateQueueEntryStatus(request)
  .then(console.log)
  .catch(console.error); // handle any errors

queues.joinQueue(request) ⇒ Promise.<void>

Adds a customer to a queue.

Kind: instance method of Queues
Returns: Promise.<void> - A promise resolving to void

Param	Type	Description
request	JoinQueueRequest	The request object
request.workspaceId	string	The workspace ID
request.customerId	string	The customer ID to add to the queue

Example

const request = {
 workspaceId: "g-7b7c46fb05",
 customerId: "4f9d5a3a-362b-7b7a-34gb-4e94969d7d2d"
};

queues.joinQueue(request)
 .then(console.log)
 .catch(console.error); // handle any errors

Tokens ⇐ AbstractBaseClient

Use the Goodtok Tokens capability to create and verify JWT tokens. Ensure the Goodtok API Server is running for the Tokens API to function.

Kind: global class
Extends: AbstractBaseClient
See: module:sdk:Client

• Tokens ⇐ AbstractBaseClient
  • new Tokens(client)
  • .createAnonymousToken(request) ⇒ Promise.<string>
  • .createToken(request) ⇒ Promise.<string>

new Tokens(client)

Constructs a new Tokens API object.

Param	Type	Description
client	Client	Object containing the client configuration

Example

const SDK = require("@goodtok/sdk");

async function createAnonymousToken() {
  const client = new SDK.Client({ workspace: "myworkspace" });
  await client.login("goodtok", "mysecretpassword");

  const tokens = new SDK.Tokens(client);

  const request = {
    ref: "myref",
    workspaceId: "g-1234567890",
    metadata: {
     customField: "customValue"
    }
  }

  const connectionObject = await tokens.createAnonymousToken(request);
  console.log(connectionObject);
}

createAnonymousToken().catch(console.error);

tokens.createAnonymousToken(request) ⇒ Promise.<string>

Creates a new anonymous token for the specified workspace, and does not require authentication.

Kind: instance method of Tokens
Returns: Promise.<string> - A promise resolving to the token
Throws:

• Will throw an error if the workspace does not have the anonymous feature enabled

Param	Type	Description
request	CreateAnonymousTokenInput	A request with claims required to create a token
request.ref	string	A reference for the anonymous user
request.workspaceId	string	The workspace ID
request.metadata	string	Custom metadata to be included in the token

Example

const request = {
  ref: "myref",
  workspaceId: "g-1234567890",
  metadata: {
   customField: "customValue"
  }
}

tokens.createAnonymousToken(request)
  .then(console.log)
  .catch(console.error) // handle any errors

tokens.createToken(request) ⇒ Promise.<string>

Creates a new token with the specified permissions.

Kind: instance method of Tokens
Returns: Promise.<string> - A promise resolving to the token
Throws:

• Will throw an error if the user is not logged in

Param	Type	Description
request	CreateTokenInput	A request with claims required to create the token
request.ref	string	A reference for the user
request.peerId	string	The peer ID for the user

Example

const request = {
  ref: "myref",
  customerId: "121a4579",
  workspaceId: "g-1234567890"
};

tokens.createToken(request)
  .then(console.log)
  .catch(console.error); // handle any errors

Users ⇐ AbstractBaseClient

Use the Goodtok Users capability to retrieve and manage users. Ensure the Goodtok API Server is running for the Users API to function.

Kind: global class
Extends: AbstractBaseClient
See: module:sdk:Client

• Users ⇐ AbstractBaseClient
  • new Users(client)
  • .getCurrentUser() ⇒ Promise.<User>
  • .getUserById(id) ⇒ Promise.<User>
  • .updateUser(request) ⇒ Promise.<UpdateUserResponse>

new Users(client)

Constructs a new Users API object.

Param	Type	Description
client	Client	Object containing the client configuration

Example

const SDK = require("@goodtok/sdk");

async function getUser() {
  const client = new SDK.Client({ workspace: "myworkspace" });
  await client.login("goodtok", "mysecretpassword");

  const users = new SDK.Users(client);
  const id = "5f9d7a3a-2b2b-4b7a-9b9b-8e9d9d9d9d9d";
  const user = await users.getUserById(id);

  console.log(user);
}

getUser().catch(console.error);

users.getCurrentUser() ⇒ Promise.<User>

Retrieves the logged-in user.

Kind: instance method of Users
Returns: Promise.<User> - A promise resolving to the user
Throws:

• Will throw an error if user is not logged in or the JWT token has expired

Example

const id = "5f9d7a3a-2b2b-4b7a-9b9b-8e9d9d9d9d9d";

users.getCurrentUser(id)
  .then(console.log)
  .catch(console.error); // handle any errors

users.getUserById(id) ⇒ Promise.<User>

Retrieves a user by its ID. The calling user must have an admin role to retrieve other users.

Kind: instance method of Users
Returns: Promise.<User> - A promise resolving to the user
Throws:

• Will throw an error if the user is not found
• If the user is not an admin and the user ID does not match the logged-in user's ID

Param	Type	Description
id	string	The user ID

Example

const id = "5f9d7a3a-2b2b-4b7a-9b9b-8e9d9d9d9d9d";

users.getUserById(id)
  .then(console.log)
  .catch(console.error); // handle any errors

users.updateUser(request) ⇒ Promise.<UpdateUserResponse>

Updates a user's details. The calling user must have an admin role to update other users.

Kind: instance method of Users
Returns: Promise.<UpdateUserResponse> - A promise resolving to the updated user's details
Throws:

• If the user is not an admin and the user ID does not match the logged-in user's ID

Param	Type	Description
request	UpdateUserRequest	A request object containing the user ID and update data
request.name	string	Optional parameter to update the user's name
request.password	string	Optional parameter to update the user's password
request.avatar	string	Optional parameter to update the user's avatar

Example

const request = {
  name: "John Doe",
  password: "mysecretpassword",
  avatar: "https://example.com/avatar.png"
};

users.updateUser(request)
  .then(console.log)
  .catch(console.error); // handle any errors

Workspaces ⇐ AbstractBaseClient

Use the Goodtok Workspaces capability to retrieve and manage workspaces. Ensure the Goodtok API Server is running for the Workspaces API to function.

Kind: global class
Extends: AbstractBaseClient
See: module:sdk:Client

• Workspaces ⇐ AbstractBaseClient
  • new Workspaces(client)
  • .createWorkspace(request) ⇒ Promise.<Workspace>
  • .getDefaultWorkspaceId() ⇒ string
  • .getDefaultWorkspace() ⇒ Promise.<Workspace>
  • .getDefaultWorkspaceMembers() ⇒ Promise.<GetMembersResponse>
  • .getWorkspaceById(id) ⇒ Promise.<Workspace>
  • .getMembersByWorkspaceId(id) ⇒ Promise.<Workspace>
  • .updateWorkspace(request) ⇒ Promise.<Workspace>
  • .getWorkspaces() ⇒ Promise.<Array.<Workspace>>
  • .addWorkspaceMember(request) ⇒ Promise.<Member>
  • .removeWorkspaceMember(id) ⇒ Promise.<void>
  • .removeWorkspace(id) ⇒ Promise.<void>
  • .resendWorkspaceMemberInvite(id) ⇒ Promise.<void>
  • .watchWorkspaceStatus(id, callback) ⇒ Unsubscribable

new Workspaces(client)

Constructs a new Workspaces API object.

Param	Type	Description
client	Client	Object containing the client configuration

Example

const SDK = require("@goodtok/sdk");

async function getWorkspace() {
  const client = new SDK.Client({ workspace: "myworkspace" });
  await client.login("goodtok", "mysecretpassword");

  const workspaces = new SDK.Workspaces(client);
  const workspace = await workspaces.getDefaultWorkspace();

  console.log(workspace);
}

getWorkspace().catch(console.error);

workspaces.createWorkspace(request) ⇒ Promise.<Workspace>

Creates a new workspace.

Kind: instance method of Workspaces
Returns: Promise.<Workspace> - A promise resolving to the created workspace

Param	Type	Description
request	CreateWorkspaceRequest	The request object containing the workspace name, timezone, and hours of operation
request.name	string	The workspace name
request.timezone	string	The workspace timezone
request.hoursOfOperation	object	The workspace hours of operation

Example

const request = {
  name: "My Workspace",
  timezone: "America/New_York",
  hoursOfOperation: {
    Monday: { from: "09:00", to: "17:00" },
    Tuesday: { from: "09:00", to: "17:00" },
    // ...
  }
};

workspaces.createWorkspace(request)
 .then(console.log)
 .catch(console.error); // handle any errors

workspaces.getDefaultWorkspaceId() ⇒ string

Retrieves the default workspace ID.

Kind: instance method of Workspaces
Returns: string - The default workspace ID
Example

workspaces.getDefaultWorkspaceId();

workspaces.getDefaultWorkspace() ⇒ Promise.<Workspace>

Retrieves the default workspace.

Kind: instance method of Workspaces
Returns: Promise.<Workspace> - A promise resolving to the workspace
Example

workspaces.getDefaultWorkspace()
  .then(console.log)
  .catch(console.error); // handle any errors

workspaces.getDefaultWorkspaceMembers() ⇒ Promise.<GetMembersResponse>

Retrieves the members for the default workspace.

Kind: instance method of Workspaces
Returns: Promise.<GetMembersResponse> - A promise resolving to the members
Example

workspaces.getDefaultWorkspaceMembers()
  .then(console.log)
  .catch(console.error); // handle any errors

workspaces.getWorkspaceById(id) ⇒ Promise.<Workspace>

Retrieves a workspace by its ID.

Kind: instance method of Workspaces
Returns: Promise.<Workspace> - A promise resolving to the workspace

Param	Type	Description
id	string	The workspace ID

Example

const id = "4f9d5a3a-362b-7b7a-34gb-4e94969d7d2d";

workspaces.getWorkspaceById(id)
  .then(console.log)
  .catch(console.error); // handle any errors

workspaces.getMembersByWorkspaceId(id) ⇒ Promise.<Workspace>

Retrieves the members for a workspace by its ID.

Kind: instance method of Workspaces
Returns: Promise.<Workspace> - A promise resolving to an object containing an array of members

Param	Type	Description
id	string	The workspace ID

Example

const id = "4f9d5a3a-362b-7b7a-34gb-4e94969d7d2d";

workspaces.getMembersByWorkspaceId(id)
  .then(console.log)
  .catch(console.error); // handle any errors

workspaces.updateWorkspace(request) ⇒ Promise.<Workspace>

Updates the details of a workspace.

Kind: instance method of Workspaces
Returns: Promise.<Workspace> - A promise resolving to the updated workspace's details

Param	Type	Description
request	UpdateWorkspaceRequest	The request object containing the workspace ID and update data
request.id	string	The workspace ID
request.name	string	The workspace name
request.timezone	string	The workspace timezone
request.hoursOfOperation	object	The workspace hours of operation

Example

const request = {
  id: "4f9d5a3a-362b-7b7a-34gb-4e94969d7d2d",
  name: "My Workspace",
  timezone: "America/New_York",
  hoursOfOperation: {
    Monday: { from: "09:00", to: "17:00" },
    Tuesday: { from: "09:00", to: "17:00" },
    // ...
  }
};

workspaces.updateWorkspace(request)
  .then(console.log)
  .catch(console.error); // handle any errors

workspaces.getWorkspaces() ⇒ Promise.<Array.<Workspace>>

Retrieves all workspaces for the authenticated user.

Kind: instance method of Workspaces
Returns: Promise.<Array.<Workspace>> - A promise resolving to an array of workspaces
Example

workspaces.getWorkspaces()
 .then(console.log)
 .catch(console.error); // handle any errors

workspaces.addWorkspaceMember(request) ⇒ Promise.<Member>

Adds a member to a workspace.

Kind: instance method of Workspaces
Returns: Promise.<Member> - A promise resolving to the added member

Param	Type	Description
request	AddWorkspaceMemberRequest	The request object containing the workspace ID and member details
request.workspaceId	string	The workspace ID
request.name	string	The member name
request.email	string	The member email
request.role	string	The member role

Example

const request = {
  workspaceId: "4f9d5a3a-362b-7b7a-34gb-4e94969d7d2d",
  name: "John Doe",
  email: "[e-mail]",
  role: "MEMBER"
};

workspaces.addWorkspaceMember(request)
  .then(console.log)
  .catch(console.error); // handle any errors

workspaces.removeWorkspaceMember(id) ⇒ Promise.<void>

Removes a member from a workspace.

Kind: instance method of Workspaces
Returns: Promise.<void> - A promise resolving to void

Param	Type	Description
id	string	The member ID

Example

const id = "4f9d5a3a-362b-7b7a-34gb-4e94969d7d2d";

workspaces.removeWorkspaceMember(id)
  .then(console.log)
  .catch(console.error); // handle any errors

workspaces.removeWorkspace(id) ⇒ Promise.<void>

Removes a workspace.

Kind: instance method of Workspaces
Returns: Promise.<void> - A promise resolving to void

Param	Type	Description
id	string	The workspace ID

Example

const id = "4f9d5a3a-362b-7b7a-34gb-4e94969d7d2d";

workspaces.removeWorkspace(id)
  .then(console.log)
  .catch(console.error); // handle any errors

workspaces.resendWorkspaceMemberInvite(id) ⇒ Promise.<void>

Resends a workspace member invite.

Kind: instance method of Workspaces
Returns: Promise.<void> - A promise resolving to void

Param	Type	Description
id	string	The member ID

Example

const id = "4f9d5a3a-362b-7b7a-34gb-4e94969d7d2d";

workspaces.resendWorkspaceMemberInvite(id)
  .then(console.log)
  .catch(console.error); // handle any errors

workspaces.watchWorkspaceStatus(id, callback) ⇒ Unsubscribable

Registers a callback for real-time updates on workspace status.

Kind: instance method of Workspaces
Returns: Unsubscribable - An object containing the unsubscribe method

Param	Type	Description
id	string	The ID of the workspace
callback	function	The callback to be invoked when the workspace status updates

Example

const id = "4f9d5a3a-362b-7b7a-34gb-4e94969d7d2d";

workspaces.watchWorkspaceStatus(id, (err, data) => {
  if (err) {
   console.error(err);
   return;
  }

  console.log(data);
});