sdk ================= SDK for Goodtok Server [![goodtok](https://img.shields.io/badge/goodtok-sdk-brightgreen.svg)](https://goodtok.io) [![Version](https://img.shields.io/npm/v/@goodtok/sdk.svg)](https://npmjs.org/package/@goodtok/sdk) [![Downloads/week](https://img.shields.io/npm/dw/@goodtok/sdk.svg)](https://npmjs.org/package/@goodtok/sdk) [![License](https://img.shields.io/npm/l/@goodtok/sdk.svg)](https://github.com/fonoster/goodtok/blob/main/package.json) * [Installation](#installation) * [APIs](#apis) # Installation ```sh-session $ npm install --save @goodtok/sdk ``` # APIs * [`Customers`](#Customers) * [`Users`](#Users) * [`Workspaces`](#Workspaces) * [`Tokens`](#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](#Customers) ⇐ AbstractBaseClient * [new Customers(client)](#new_Customers_new) * [.getCustomerById(request)](#Customers+getCustomerById) ⇒ Promise.<Customer> * [.getOrdersByCustomerId(request)](#Customers+getOrdersByCustomerId) ⇒ Promise.<Array.<Order>> * [.getCustomerInDefaultWorkspace(id)](#Customers+getCustomerInDefaultWorkspace) ⇒ Promise.<Customer> ### new Customers(client) Constructs a new Customers API object. | Param | Type | Description | | --- | --- | --- | | client | Client | Object containing the client configuration | **Example** ```js 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](#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** ```js 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](#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** ```js 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](#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** ```js 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](#Queues) ⇐ AbstractBaseClient * [new Queues(client)](#new_Queues_new) * [.getDefaultWorkspaceQueue()](#Queues+getDefaultWorkspaceQueue) ⇒ Promise.<GetQueueResponse> * [.getQueueByWorkspaceId(id)](#Queues+getQueueByWorkspaceId) ⇒ Promise.<Workspace> * [.watchQueue(id, callback)](#Queues+watchQueue) * [.updateQueueEntryStatus(request)](#Queues+updateQueueEntryStatus) ⇒ Promise.<void> * [.joinQueue(request)](#Queues+joinQueue) ⇒ Promise.<void> ### new Queues(client) Constructs a new Queues API object. | Param | Type | Description | | --- | --- | --- | | client | Client | Object containing the client configuration | **Example** ```js 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](#Queues) **Returns**: Promise.<GetQueueResponse> - A promise resolving to the queue **Example** ```js 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](#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** ```js 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](#Queues) | Param | Type | Description | | --- | --- | --- | | id | string | The ID of the workspace | | callback | function | The callback to be invoked when a queue entry updates | **Example** ```js 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](#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** ```js 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](#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** ```js 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](#Tokens) ⇐ AbstractBaseClient * [new Tokens(client)](#new_Tokens_new) * [.createAnonymousToken(request)](#Tokens+createAnonymousToken) ⇒ Promise.<string> * [.createToken(request)](#Tokens+createToken) ⇒ Promise.<string> ### new Tokens(client) Constructs a new Tokens API object. | Param | Type | Description | | --- | --- | --- | | client | Client | Object containing the client configuration | **Example** ```js 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](#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** ```js 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](#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** ```js 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](#Users) ⇐ AbstractBaseClient * [new Users(client)](#new_Users_new) * [.getCurrentUser()](#Users+getCurrentUser) ⇒ Promise.<User> * [.getUserById(id)](#Users+getUserById) ⇒ Promise.<User> * [.updateUser(request)](#Users+updateUser) ⇒ Promise.<UpdateUserResponse> ### new Users(client) Constructs a new Users API object. | Param | Type | Description | | --- | --- | --- | | client | Client | Object containing the client configuration | **Example** ```js 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](#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** ```js 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](#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** ```js 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](#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** ```js 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](#Workspaces) ⇐ AbstractBaseClient * [new Workspaces(client)](#new_Workspaces_new) * [.createWorkspace(request)](#Workspaces+createWorkspace) ⇒ Promise.<Workspace> * [.getDefaultWorkspaceId()](#Workspaces+getDefaultWorkspaceId) ⇒ string * [.getDefaultWorkspace()](#Workspaces+getDefaultWorkspace) ⇒ Promise.<Workspace> * [.getDefaultWorkspaceMembers()](#Workspaces+getDefaultWorkspaceMembers) ⇒ Promise.<GetMembersResponse> * [.getWorkspaceById(id)](#Workspaces+getWorkspaceById) ⇒ Promise.<Workspace> * [.getMembersByWorkspaceId(id)](#Workspaces+getMembersByWorkspaceId) ⇒ Promise.<Workspace> * [.updateWorkspace(request)](#Workspaces+updateWorkspace) ⇒ Promise.<Workspace> * [.getWorkspaces()](#Workspaces+getWorkspaces) ⇒ Promise.<Array.<Workspace>> * [.addWorkspaceMember(request)](#Workspaces+addWorkspaceMember) ⇒ Promise.<Member> * [.removeWorkspaceMember(id)](#Workspaces+removeWorkspaceMember) ⇒ Promise.<void> * [.removeWorkspace(id)](#Workspaces+removeWorkspace) ⇒ Promise.<void> * [.resendWorkspaceMemberInvite(id)](#Workspaces+resendWorkspaceMemberInvite) ⇒ Promise.<void> * [.watchWorkspaceStatus(id, callback)](#Workspaces+watchWorkspaceStatus) ⇒ Unsubscribable ### new Workspaces(client) Constructs a new Workspaces API object. | Param | Type | Description | | --- | --- | --- | | client | Client | Object containing the client configuration | **Example** ```js 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](#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** ```js 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](#Workspaces) **Returns**: string - The default workspace ID **Example** ```js workspaces.getDefaultWorkspaceId(); ``` ### workspaces.getDefaultWorkspace() ⇒ Promise.<Workspace> Retrieves the default workspace. **Kind**: instance method of [Workspaces](#Workspaces) **Returns**: Promise.<Workspace> - A promise resolving to the workspace **Example** ```js 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](#Workspaces) **Returns**: Promise.<GetMembersResponse> - A promise resolving to the members **Example** ```js 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](#Workspaces) **Returns**: Promise.<Workspace> - A promise resolving to the workspace | Param | Type | Description | | --- | --- | --- | | id | string | The workspace ID | **Example** ```js 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](#Workspaces) **Returns**: Promise.<Workspace> - A promise resolving to an object containing an array of members | Param | Type | Description | | --- | --- | --- | | id | string | The workspace ID | **Example** ```js 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](#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** ```js 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](#Workspaces) **Returns**: Promise.<Array.<Workspace>> - A promise resolving to an array of workspaces **Example** ```js 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](#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** ```js const request = { workspaceId: "4f9d5a3a-362b-7b7a-34gb-4e94969d7d2d", name: "John Doe", email: "jhon@example.com", 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](#Workspaces) **Returns**: Promise.<void> - A promise resolving to void | Param | Type | Description | | --- | --- | --- | | id | string | The member ID | **Example** ```js 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](#Workspaces) **Returns**: Promise.<void> - A promise resolving to void | Param | Type | Description | | --- | --- | --- | | id | string | The workspace ID | **Example** ```js 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](#Workspaces) **Returns**: Promise.<void> - A promise resolving to void | Param | Type | Description | | --- | --- | --- | | id | string | The member ID | **Example** ```js 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](#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** ```js const id = "4f9d5a3a-362b-7b7a-34gb-4e94969d7d2d"; workspaces.watchWorkspaceStatus(id, (err, data) => { if (err) { console.error(err); return; } console.log(data); }); ```