@signalhousellc/sdk 1.0.38 → 1.0.41

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@signalhousellc/sdk",
-  "version": "1.0.38",
+  "version": "1.0.41",
   "description": "Signal House SDK for use with the Signal House platform",
   "type": "module",
   "main": "src/SignalHouseSDK.js",

package/src/SignalHouseSDK.js

@@ -15,6 +15,7 @@ import { Groups } from "./domains/Groups.js";
 import { Landings } from "./domains/Landings.js";
 import { Messages } from "./domains/Messages.js";
 import { Numbers } from "./domains/Numbers.js";
+import { Onboarding } from "./domains/Onboarding.js";
 import { Shortlinks } from "./domains/Shortlinks.js";
 import { Subgroups } from "./domains/Subgroups.js";
 import { Subscriptions } from "./domains/Subscriptions.js";
@@ -58,6 +59,7 @@ export class SignalHouseSDK {
 		this.landings = new Landings(client, multipartClient, this.enableAdmin);
 		this.messages = new Messages(client, multipartClient, this.enableAdmin);
 		this.numbers = new Numbers(client, this.enableAdmin);
+		this.onboarding = new Onboarding(client, this.enableAdmin);
 		this.shortlinks = new Shortlinks(client, this.enableAdmin);
 		this.subgroups = new Subgroups(client, this.enableAdmin);
 		this.subscriptions = new Subscriptions(client, this.enableAdmin);

package/src/domains/Numbers.js

@@ -93,7 +93,10 @@ export class Numbers {
 	}
 
 	/**
-	 * Purchase phone numbers by providing a list of phone numbers and the subgroup ID to assign them to
+	 * Purchase phone numbers by providing a list of phone numbers and the subgroup ID to assign them to.
+	 *
+	 * Each requested number is queued and processed independently. Per-number success or failure is
+	 * delivered via `NUMBER_PURCHASE_SUCCESSFUL` / `NUMBER_PURCHASE_FAILED` webhooks — not in this response.
 	 * @async
 	 * @roles api, admin, developer, billing, user
 	 * @param {Object} params - The parameters for purchasing phone numbers
@@ -101,7 +104,7 @@ export class Numbers {
 	 * @param {string} params.subgroupId - The ID of the subgroup to assign the purchased phone numbers to
 	 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
 	 * @throws {Error} Throws an error if the phoneNumbers or subgroupId parameter is missing
-	 * @returns {Promise<Object>} A promise that resolves to the result of the purchase operation
+	 * @returns {Promise<Object>} A promise that resolves to `{ message }` once the request is queued.
 	 */
 	async purchasePhoneNumber({ phoneNumbers, subgroupId, options = {} }) {
 		this.client._require({ phoneNumbers, subgroupId });

package/src/domains/Onboarding.js

@@ -0,0 +1,39 @@
+export class Onboarding {
+	constructor(client, enableAdmin) {
+		this.client = client;
+		this.enableAdmin = enableAdmin;
+
+		// Hidden Admin namespace INSIDE the domain
+		if (enableAdmin) {
+			this.admin = {
+				/**
+				 * Get all onboarding records (one per group). Staff-only.
+				 * @async
+				 * @roles signalhouse
+				 * @param {Object} [params] - Optional parameters
+				 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
+				 * @returns {Promise<Object>} - Array of onboarding records
+				 */
+				getOnboardings: async ({ options = {} } = {}) => {
+					return this.client(`/group/onboarding`, { method: "GET", ...options });
+				},
+
+				/**
+				 * Get a single onboarding record by group ID. Staff-only.
+				 * @async
+				 * @roles signalhouse
+				 * @param {Object} params
+				 * @param {string} params.groupId - The group ID whose onboarding record to retrieve
+				 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
+				 * @throws {Error} Throws an error if the groupId parameter is missing
+				 * @returns {Promise<Object>} - The onboarding record
+				 */
+				getOnboarding: async ({ groupId, options = {} }) => {
+					this.client._require({ groupId });
+					const safeGroupId = encodeURIComponent(groupId);
+					return this.client(`/group/onboarding/${safeGroupId}`, { method: "GET", ...options });
+				},
+			};
+		}
+	}
+}

package/src/domains/Users.js

@@ -1,204 +1,204 @@
-/**
- * @typedef {Object} CreateUserData
- * @property {string} groupId - The ID of the group to which the user belongs (must start with "G" and be at least 8 characters long)
- * @property {string} role - The role of the user (admin, developer, billing, user)
- * @property {string} password - The password for the user (must be at least 8 characters long)
- * @property {string} email - The email address of the user (must be a valid email format)
- * @property {string} [firstName] - The first name of the user (optional)
- * @property {string} [lastName] - The last name of the user (optional)
- * @property {string} [companyName] - The company name associated with the user (optional)
- * @property {string} [phone] - The phone number of the user (optional)
- * @property {string} [profileImageLink] - A URL to the user's profile image (optional, must be a valid URL format if provided)
- * @property {string} [addressLine1] - The first line of the user's address (optional)
- * @property {string} [addressLine2] - The second line of the user's address (optional)
- * @property {string} [city] - The city of the user's address (optional)
- * @property {string} [state] - The state of the user's address (optional)
- * @property {string} [country] - The country of the user's address (optional)
- * @property {string} [postalCode] - The postal code of the user's address (optional)
- * @property {string} [signupSource] - The source from which the user signed up (optional)
- */
-
-/**
- * @typedef {Object} CreateServiceUserData
- * @property {string} groupId - The ID of the group to which the service user belongs (required)
- * @property {string} name - The name of the service user (required)
- * @property {string} role - The role of the service user (admin, developer, billing, user) (required)
- */
-
-/**
- * @typedef {Object} UpdateUserData
- * @property {string} [role] - The role of the user (admin, developer, billing, user)
- * @property {string} [email] - The email address of the user (must be a valid email format if provided)
- * @property {string} [firstName] - The first name of the user (optional)
- * @property {string} [lastName] - The last name of the user (optional)
- * @property {string} [companyName] - The company name associated with the user (optional)
- * @property {string} [phone] - The phone number of the user (optional)
- * @property {string} [profileImageLink] - A URL to the user's profile image (optional, must be a valid URL format if provided)
- * @property {string} [addressLine1] - The first line of the user's address (optional)
- * @property {string} [addressLine2] - The second line of the user's address (optional)
- * @property {string} [city] - The city of the user's address (optional)
- * @property {string} [state] - The state of the user's address (optional)
- * @property {string} [country] - The country of the user's address (optional)
- * @property {string} [postalCode] - The postal code of the user's address (optional)
- * @property {string} [status] - The status of the user (e.g., "active", "inactive")
- */
-
-export class Users {
-	constructor(client, enableAdmin) {
-		this.client = client;
-		this.enableAdmin = enableAdmin;
-
-		if (enableAdmin) {
-			this.admin = {
-				/**
-				 * Get a list of users with optional filters.
-				 * @roles signalhouse
-				 * @param {Object} params - The parameters for getting users
-				 * @param {string} [params.email] - Filter users by email (partial match)
-				 * @param {string} [params.userType] - Filter users by type (user, service)
-				 * @param {number} [params.page] - Page number for pagination
-				 * @param {number} [params.limit] - Items per page
-				 * @param {string} [params.search] - Search users by email (case-insensitive)
-				 * @param {string} [params.sortBy] - Field to sort by (createdAt, email, activeGroupId, companyName, status, _id)
-				 * @param {string} [params.sortOrder] - Sort direction (asc, desc)
-				 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
-				 * @returns {Promise<Object>} - A promise that resolves to the list of users
-				 */
-				getUsers: async ({ email, userType, page, limit, search, sortBy, sortOrder, options = {} }) => {
-					const filters = { email, userType, page, limit, search, sortBy, sortOrder };
-					const queryString = this.client._getQueryString(filters);
-					return this.client(`/user${queryString}`, { method: "GET", ...options });
-				},
-
-				/**
-				 * Create a new internal user (admin or service user) with the specified data.
-				 * @roles signalhouse
-				 * @param {Object} params - The parameters for creating an internal user
-				 * @param {CreateServiceUserData} params.data - The data for the new internal user
-				 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
-				 * @returns {Promise<Object>} - A promise that resolves to the created internal user
-				 */
-				createInternalUser: async ({ data, options = {} }) => {
-					this.client._require({ data: data });
-					return this.client(`/user/signalhouse`, { method: "POST", body: data, ...options });
-				},
-			};
-		}
-	}
-
-	/**
-	 * Get a list of users with optional filters
-	 * @async
-	 * @roles api, admin, self
-	 * @param {Object} params - The parameters for getting users
-	 * @param {string} [params.id] - Filter by user ID
-	 * @param {string} [params.groupId] - Filter by group ID
-	 * @param {string} [params.userType] - Filter by user type (user, service)
-	 * @param {number} [params.page] - Page number for pagination
-	 * @param {number} [params.limit] - Items per page
-	 * @param {string} [params.search] - Search users by email (case-insensitive)
-	 * @param {string} [params.sortBy] - Field to sort by (createdAt, email, activeGroupId, companyName, status, _id)
-	 * @param {string} [params.sortOrder] - Sort direction (asc, desc)
-	 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
-	 * @returns {Promise<Object>} - A promise that resolves to the list of users
-	 */
-	async getUsers({ id, groupId, userType, page, limit, search, sortBy, sortOrder, options = {} }) {
-		const filters = { id, groupId, userType, page, limit, search, sortBy, sortOrder };
-		const queryString = this.client._getQueryString(filters);
-		return this.client(`/user${queryString}`, { method: "GET", ...options });
-	}
-
-	/**
-	 * Create a new user with the specified user data
-	 * @async
-	 * @roles api, admin
-	 * @param {Object} params - The parameters for creating a user (see CreateUserData typedef for details)
-	 * @param {CreateUserData} params.data - The data for the new user
-	 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
-	 * @throws {Error} Throws an error if required fields in the data parameter are missing
-	 * @returns {Promise<Object>} - A promise that resolves to the created user
-	 */
-	async createUser({ data, options = {} }) {
-		this.client._require({ data: data });
-		return this.client(`/user`, { method: "POST", body: data, ...options });
-	}
-
-	/**
-	 * Create a new service user with the specified user data. Used for creating API keys and other non-human users.
-	 * @async
-	 * @roles admin, developer
-	 * @param {Object} params - The parameters for creating a service user (see CreateServiceUserData typedef for details)
-	 * @param {CreateServiceUserData} params.data - The data for the new service user
-	 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
-	 * @throws {Error} Throws an error if required fields in the data parameter are missing
-	 * @returns {Promise<Object>} - A promise that resolves to the created service user
-	 */
-	async createServiceUser({ data, options = {} }) {
-		this.client._require({ data: data });
-		return this.client(`/user/serviceuser`, { method: "POST", body: data, ...options });
-	}
-
-	/**
-	 * Update an existing user's information with the specified user data
-	 * @async
-	 * @roles api, admin, self
-	 * @param {Object} params - The parameters for updating a user (see UpdateUserData typedef for details)
-	 * @param {string} params.id - The ID of the user to update
-	 * @param {UpdateUserData} params.data - The data to update for the user
-	 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
-	 * @throws {Error} Throws an error if required fields in the data parameter are missing
-	 * @returns {Promise<Object>} - A promise that resolves to the updated user
-	 */
-	async updateUser({ id, data, options = {} }) {
-		this.client._require({ id, data: data });
-		const safeId = encodeURIComponent(id);
-		return this.client(`/user/${safeId}`, { method: "PUT", body: data, ...options });
-	}
-
-	/**
-	 * Delete a user by their ID (mark as inactive)
-	 * @async
-	 * @roles api, admin
-	 * @param {Object} params - The parameters for deleting a user
-	 * @param {string} params.id - The ID of the user to delete
-	 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
-	 * @throws {Error} Throws an error if the id parameter is missing
-	 * @returns {Promise<Object>} - A promise that resolves to the deleted user
-	 */
-	async deleteUser({ id, options = {} }) {
-		this.client._require({ id });
-		const safeId = encodeURIComponent(id);
-		return this.client(`/user/${safeId}`, { method: "DELETE", ...options });
-	}
-
-	/**
-	 * Get notification preferences for a user
-	 * @async
-	 * @roles api, admin, self
-	 * @param {Object} params
-	 * @param {string} params.id - The ID of the user
-	 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
-	 * @returns {Promise<Object>} The response from the server
-	 */
-	async getNotificationPreferences({ id, options = {} }) {
-		this.client._require({ id });
-		const safeId = encodeURIComponent(id);
-		return this.client(`/user/${safeId}/notification-preferences`, { method: "GET", ...options });
-	}
-
-	/**
-	 * Update notification preferences for a user
-	 * @async
-	 * @roles api, admin, self
-	 * @param {Object} params
-	 * @param {string} params.id - The ID of the user
-	 * @param {Array<{name: string, web: boolean, email: boolean}>} params.notificationPreferences - Array of notification preference objects
-	 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
-	 * @returns {Promise<Object>} The response from the server
-	 */
-	async updateNotificationPreferences({ id, notificationPreferences, options = {} }) {
-		this.client._require({ id, notificationPreferences });
-		const safeId = encodeURIComponent(id);
-		return this.client(`/user/${safeId}/notification-preferences`, { method: "PUT", body: { notificationPreferences }, ...options });
-	}
-}
+/**
+ * @typedef {Object} CreateUserData
+ * @property {string} groupId - The ID of the group to which the user belongs (must start with "G" and be at least 8 characters long)
+ * @property {string} role - The role of the user (admin, developer, billing, user)
+ * @property {string} password - The password for the user (must be at least 8 characters long)
+ * @property {string} email - The email address of the user (must be a valid email format)
+ * @property {string} [firstName] - The first name of the user (optional)
+ * @property {string} [lastName] - The last name of the user (optional)
+ * @property {string} [companyName] - The company name associated with the user (optional)
+ * @property {string} [phone] - The phone number of the user (optional)
+ * @property {string} [profileImageLink] - A URL to the user's profile image (optional, must be a valid URL format if provided)
+ * @property {string} [addressLine1] - The first line of the user's address (optional)
+ * @property {string} [addressLine2] - The second line of the user's address (optional)
+ * @property {string} [city] - The city of the user's address (optional)
+ * @property {string} [state] - The state of the user's address (optional)
+ * @property {string} [country] - The country of the user's address (optional)
+ * @property {string} [postalCode] - The postal code of the user's address (optional)
+ * @property {string} [signupSource] - The source from which the user signed up (optional)
+ */
+
+/**
+ * @typedef {Object} CreateServiceUserData
+ * @property {string} groupId - The ID of the group to which the service user belongs (required)
+ * @property {string} name - The name of the service user (required)
+ * @property {string} role - The role of the service user (admin, developer, billing, user) (required)
+ */
+
+/**
+ * @typedef {Object} UpdateUserData
+ * @property {string} [role] - The role of the user (admin, developer, billing, user)
+ * @property {string} [email] - The email address of the user (must be a valid email format if provided)
+ * @property {string} [firstName] - The first name of the user (optional)
+ * @property {string} [lastName] - The last name of the user (optional)
+ * @property {string} [companyName] - The company name associated with the user (optional)
+ * @property {string} [phone] - The phone number of the user (optional)
+ * @property {string} [profileImageLink] - A URL to the user's profile image (optional, must be a valid URL format if provided)
+ * @property {string} [addressLine1] - The first line of the user's address (optional)
+ * @property {string} [addressLine2] - The second line of the user's address (optional)
+ * @property {string} [city] - The city of the user's address (optional)
+ * @property {string} [state] - The state of the user's address (optional)
+ * @property {string} [country] - The country of the user's address (optional)
+ * @property {string} [postalCode] - The postal code of the user's address (optional)
+ * @property {string} [status] - The status of the user (e.g., "active", "inactive")
+ */
+
+export class Users {
+	constructor(client, enableAdmin) {
+		this.client = client;
+		this.enableAdmin = enableAdmin;
+
+		if (enableAdmin) {
+			this.admin = {
+				/**
+				 * Get a list of users with optional filters.
+				 * @roles signalhouse
+				 * @param {Object} params - The parameters for getting users
+				 * @param {string} [params.email] - Filter users by email (partial match)
+				 * @param {string} [params.userType] - Filter users by type (user, service)
+				 * @param {number} [params.page] - Page number for pagination
+				 * @param {number} [params.limit] - Items per page
+				 * @param {string} [params.search] - Search users by email (case-insensitive)
+				 * @param {string} [params.sortBy] - Field to sort by (createdAt, email, activeGroupId, companyName, status, _id)
+				 * @param {string} [params.sortOrder] - Sort direction (asc, desc)
+				 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
+				 * @returns {Promise<Object>} - A promise that resolves to the list of users
+				 */
+				getUsers: async ({ email, userType, page, limit, search, sortBy, sortOrder, options = {} }) => {
+					const filters = { email, userType, page, limit, search, sortBy, sortOrder };
+					const queryString = this.client._getQueryString(filters);
+					return this.client(`/user${queryString}`, { method: "GET", ...options });
+				},
+
+				/**
+				 * Create a new internal user (admin or service user) with the specified data.
+				 * @roles signalhouse
+				 * @param {Object} params - The parameters for creating an internal user
+				 * @param {CreateServiceUserData} params.data - The data for the new internal user
+				 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
+				 * @returns {Promise<Object>} - A promise that resolves to the created internal user
+				 */
+				createInternalUser: async ({ data, options = {} }) => {
+					this.client._require({ data: data });
+					return this.client(`/user/signalhouse`, { method: "POST", body: data, ...options });
+				},
+			};
+		}
+	}
+
+	/**
+	 * Get a list of users with optional filters
+	 * @async
+	 * @roles api, admin, self
+	 * @param {Object} params - The parameters for getting users
+	 * @param {string} [params.id] - Filter by user ID
+	 * @param {string} [params.groupId] - Filter by group ID
+	 * @param {string} [params.userType] - Filter by user type (user, service)
+	 * @param {number} [params.page] - Page number for pagination
+	 * @param {number} [params.limit] - Items per page
+	 * @param {string} [params.search] - Search users by email (case-insensitive)
+	 * @param {string} [params.sortBy] - Field to sort by (createdAt, email, activeGroupId, companyName, status, _id)
+	 * @param {string} [params.sortOrder] - Sort direction (asc, desc)
+	 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
+	 * @returns {Promise<Object>} - A promise that resolves to the list of users
+	 */
+	async getUsers({ id, groupId, userType, page, limit, search, sortBy, sortOrder, options = {} }) {
+		const filters = { id, groupId, userType, page, limit, search, sortBy, sortOrder };
+		const queryString = this.client._getQueryString(filters);
+		return this.client(`/user${queryString}`, { method: "GET", ...options });
+	}
+
+	/**
+	 * Create a new user with the specified user data
+	 * @async
+	 * @roles api, admin
+	 * @param {Object} params - The parameters for creating a user (see CreateUserData typedef for details)
+	 * @param {CreateUserData} params.data - The data for the new user
+	 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
+	 * @throws {Error} Throws an error if required fields in the data parameter are missing
+	 * @returns {Promise<Object>} - A promise that resolves to the created user
+	 */
+	async createUser({ data, options = {} }) {
+		this.client._require({ data: data });
+		return this.client(`/user`, { method: "POST", body: data, ...options });
+	}
+
+	/**
+	 * Create a new service user with the specified user data. Used for creating API keys and other non-human users.
+	 * @async
+	 * @roles admin, developer
+	 * @param {Object} params - The parameters for creating a service user (see CreateServiceUserData typedef for details)
+	 * @param {CreateServiceUserData} params.data - The data for the new service user
+	 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
+	 * @throws {Error} Throws an error if required fields in the data parameter are missing
+	 * @returns {Promise<Object>} - A promise that resolves to the created service user
+	 */
+	async createServiceUser({ data, options = {} }) {
+		this.client._require({ data: data });
+		return this.client(`/user/serviceuser`, { method: "POST", body: data, ...options });
+	}
+
+	/**
+	 * Update an existing user's information with the specified user data
+	 * @async
+	 * @roles api, admin, self
+	 * @param {Object} params - The parameters for updating a user (see UpdateUserData typedef for details)
+	 * @param {string} params.id - The ID of the user to update
+	 * @param {UpdateUserData} params.data - The data to update for the user
+	 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
+	 * @throws {Error} Throws an error if required fields in the data parameter are missing
+	 * @returns {Promise<Object>} - A promise that resolves to the updated user
+	 */
+	async updateUser({ id, data, options = {} }) {
+		this.client._require({ id, data: data });
+		const safeId = encodeURIComponent(id);
+		return this.client(`/user/${safeId}`, { method: "PUT", body: data, ...options });
+	}
+
+	/**
+	 * Delete a user by their ID (mark as inactive)
+	 * @async
+	 * @roles api, admin
+	 * @param {Object} params - The parameters for deleting a user
+	 * @param {string} params.id - The ID of the user to delete
+	 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
+	 * @throws {Error} Throws an error if the id parameter is missing
+	 * @returns {Promise<Object>} - A promise that resolves to the deleted user
+	 */
+	async deleteUser({ id, options = {} }) {
+		this.client._require({ id });
+		const safeId = encodeURIComponent(id);
+		return this.client(`/user/${safeId}`, { method: "DELETE", ...options });
+	}
+
+	/**
+	 * Get notification preferences for a user
+	 * @async
+	 * @roles api, admin, self
+	 * @param {Object} params
+	 * @param {string} params.id - The ID of the user
+	 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
+	 * @returns {Promise<Object>} The response from the server
+	 */
+	async getNotificationPreferences({ id, options = {} }) {
+		this.client._require({ id });
+		const safeId = encodeURIComponent(id);
+		return this.client(`/user/${safeId}/notification-preferences`, { method: "GET", ...options });
+	}
+
+	/**
+	 * Update notification preferences for a user
+	 * @async
+	 * @roles api, admin, self
+	 * @param {Object} params
+	 * @param {string} params.id - The ID of the user
+	 * @param {Array<{name: string, web: boolean, email: boolean}>} params.notificationPreferences - Array of notification preference objects
+	 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
+	 * @returns {Promise<Object>} The response from the server
+	 */
+	async updateNotificationPreferences({ id, notificationPreferences, options = {} }) {
+		this.client._require({ id, notificationPreferences });
+		const safeId = encodeURIComponent(id);
+		return this.client(`/user/${safeId}/notification-preferences`, { method: "PUT", body: { notificationPreferences }, ...options });
+	}
+}