@signalhousellc/sdk 1.0.37 → 1.0.39

package/package.json

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

package/src/domains/Campaigns.js

@@ -119,11 +119,14 @@ export class Campaigns {
 	 * @param {number} [params.page] - The page number for pagination
 	 * @param {number} [params.limit] - The number of items per page
 	 * @param {string} [params.status] - The status of the campaign to filter by
+	 * @param {string} [params.search] - Search term to filter campaigns by campaignId or brandId
+	 * @param {string} [params.sortBy] - Field to sort by (e.g. "createdAt", "campaignId", "brandId", "groupId", "subgroupId", "usecase", "status")
+	 * @param {string} [params.sortOrder] - Sort direction ("asc" or "desc")
 	 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
-	 * @returns {Promise<Array>} The response from the server
+	 * @returns {Promise<Array|Object>} The response from the server - array when unpaginated, or { data, total, page, limit, totalPages } when paginated
 	 */
-	async getCampaigns({ id, brandId, subgroupId, groupId, page, limit, status, options = {} }) {
-		const filters = { id, brandId, subgroupId, groupId, page, limit, status };
+	async getCampaigns({ id, brandId, subgroupId, groupId, page, limit, status, search, sortBy, sortOrder, options = {} }) {
+		const filters = { id, brandId, subgroupId, groupId, page, limit, status, search, sortBy, sortOrder };
 		const queryString = this.client._getQueryString(filters);
 		return this.client(`/campaign${queryString}`, { method: "GET", ...options });
 	}

package/src/domains/Numbers.js

@@ -93,15 +93,19 @@ 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.
+	 *
+	 * Numbers already owned (by this subgroup or another) are skipped; only the remaining numbers are queued
+	 * for purchase and the response `message` names each skipped number and its reason. The request fails
+	 * with an error ONLY when every requested number is already owned.
 	 * @async
 	 * @roles api, admin, developer, billing, user
 	 * @param {Object} params - The parameters for purchasing phone numbers
 	 * @param {string[]} params.phoneNumbers - The list of phone numbers to purchase
 	 * @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
+	 * @throws {Error} Throws an error if the phoneNumbers or subgroupId parameter is missing, or if every requested number is already owned
+	 * @returns {Promise<Object>} A promise that resolves to `{ message }`. The message describes any skipped numbers when some requested numbers were already owned.
 	 */
 	async purchasePhoneNumber({ phoneNumbers, subgroupId, options = {} }) {
 		this.client._require({ phoneNumbers, subgroupId });

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 });
+	}
+}