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: "[email protected]",
  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);
});