@b-jones-rfd/qualtrics-api-tasks 0.2.0 → 0.3.0

package/dist/index.mjs

@@ -29,65 +29,6 @@ function getAuthHeaders(apiToken, bearerToken) {
   );
 }
 
-// src/utils/poll.ts
-async function poll({
-  fn,
-  validate,
-  interval,
-  maxAttempts
-}) {
-  let attempts = 0;
-  const executePoll = async (resolve, reject) => {
-    try {
-      const result = await fn();
-      attempts++;
-      if (validate(result)) {
-        return resolve(result);
-      } else if (maxAttempts && attempts === maxAttempts) {
-        return reject(new Error("Exceeded max attempts"));
-      } else {
-        setTimeout(executePoll, interval, resolve, reject);
-      }
-    } catch (error) {
-      reject(new Error(`Poll function execution failed: ${error}`));
-    }
-  };
-  return new Promise(executePoll);
-}
-
-// src/methods/exportResponses.ts
-var exportResponses = (connectionOptions) => async (responseOptions) => {
-  try {
-    const startResponseAction = startResponseExport(connectionOptions);
-    const startResponse = await startResponseAction(responseOptions);
-    if (!startResponse.success)
-      return failure(startResponse.error);
-    const exportProgressAction = getResponseExportProgress(connectionOptions);
-    const progressResponse = await poll({
-      fn: async () => await exportProgressAction({
-        exportProgressId: startResponse.data.progressId,
-        surveyId: responseOptions.surveyId,
-        bearerToken: responseOptions.bearerToken
-      }),
-      validate: (res) => res.success && res.data.percentComplete === 100,
-      interval: 1,
-      maxAttempts: 60
-    });
-    if (!progressResponse.success)
-      return failure(progressResponse.error);
-    const getFileResponseAction = getResponseExportFile(connectionOptions);
-    const fileResponse = await getFileResponseAction({
-      surveyId: responseOptions.surveyId,
-      fileId: progressResponse.data.fileId,
-      bearerToken: responseOptions.bearerToken
-    });
-    return fileResponse;
-  } catch (error) {
-    const message = getErrorMessage(error);
-    return failure(message);
-  }
-};
-
 // src/utils/parsers.ts
 function safeParseBearerToken(response) {
   return response?.access_token && typeof response.access_token === "string" ? success(response.access_token) : failure("Incorrect token format");
@@ -101,6 +42,33 @@ function safeParseStartFileExportResponse(response) {
 function safeParseFileProgressResponse(response) {
   return "result" in response ? "fileId" in response.result && "percentComplete" in response.result && "status" in response.result ? success(response.result) : failure("File Progress Response invalid format") : "error" in response ? failure(`${response.error.errorCode}: ${response.error.errorMessage}`) : failure(`Unable to parse File Progress Response`);
 }
+function safeParseCreateMailingListResponse(response) {
+  return "result" in response ? "id" in response.result ? success(response.result.id) : failure(`Id missing in Create Mailing List Response`) : failure(`Unable to parse Create Mailing List Response`);
+}
+function safeParseStartContactsImportResponse(response) {
+  return "result" in response ? "id" in response.result && "contacts" in response.result && "tracking" in response.result && "status" in response.result ? success(response.result) : failure("Start contacts import response invalid format") : failure(`Unable to parse Start Contacts Import Response`);
+}
+function safeParseContactsImportSummary(response) {
+  return "result" in response ? "percentComplete" in response.result && "contacts" in response.result && "invalidEmails" in response.result && "transactions" in response.result && "status" in response.result ? success(response.result) : failure("Contacts import summary response invalid format") : failure(`Unable to parse Contacts Import Summary Response`);
+}
+function safeParseContactsImportStatus(response) {
+  return "result" in response ? "percentComplete" in response.result && "contacts" in response.result && "transactions" in response.result && "status" in response.result ? success(response.result) : failure("Contacts import summary response invalid format") : failure(`Unable to parse Contacts Import Summary Response`);
+}
+function safeParseCreateDistributionResponse(response) {
+  return "result" in response ? "id" in response.result ? success(response.result.id) : failure(`Id missing in Create Distribution Response`) : failure(`Unable to parse Create Distribution Response`);
+}
+function safeParseCreateReminderResponse(response) {
+  return "result" in response ? "distributionId" in response.result ? success(response.result.distributionId) : failure(`distributionId missing in Create Reminder Response`) : failure(`Unable to parse Create Reminder Response`);
+}
+function safeParseListLibraryMessages(response) {
+  return "result" in response ? "elements" in response.result && Array.isArray(response.result.elements) ? success(response.result) : failure(`elements missing in List Library Messages response`) : failure(`Unable to parse List Library Messages response`);
+}
+function safeParseGetDistribution(response) {
+  return "result" in response ? "id" in response.result && "stats" in response.result ? success(response.result) : failure(`Properties missing in Get Distribution response`) : failure(`Unable to parse Get Distribution response`);
+}
+function safeParseListDistributions(response) {
+  return "result" in response ? "elements" in response.result ? success(response.result) : failure(`elements missing in List Distributions response`) : failure(`Unable to parse List Distribution response`);
+}
 
 // src/qualtrics/index.ts
 async function execute(config) {
@@ -142,25 +110,94 @@ async function execute(config) {
   }
 }
 
-// src/methods/getBearerToken.ts
-var getBearerToken = (connectionOptions) => async ({ clientId, clientSecret, scope }) => {
-  const route = `/oauth2/token`;
+// src/methods/distributions/createDistribution.ts
+var createDistribution = (connectionOptions) => async ({
+  libraryId,
+  messageId,
+  messageText,
+  mailingListId,
+  contactId,
+  transactionBatchId,
+  fromEmail,
+  replyToEmail,
+  fromName,
+  subject,
+  surveyId,
+  expirationDate,
+  type,
+  embeddedData,
+  sendDate,
+  bearerToken = void 0
+}) => {
+  const route = `/API/v3/distributions`;
   try {
-    const { datacenterId, timeout } = connectionOptions;
-    const headers = new Headers({
-      Authorization: "Basic " + Buffer.from(`${clientId}:${clientSecret}`).toString("base64")
+    const headers = getAuthHeaders(connectionOptions.apiToken, bearerToken);
+    const body = JSON.stringify({
+      message: {
+        libraryId,
+        messageId,
+        messageText
+      },
+      recipients: {
+        mailingListId,
+        contactId,
+        transactionBatchId
+      },
+      header: {
+        fromEmail,
+        replyToEmail,
+        fromName,
+        subject
+      },
+      surveyLink: {
+        surveyId,
+        expirationDate,
+        type
+      },
+      embeddedData,
+      sendDate
     });
-    const body = new FormData();
-    body.append("grant_type", "client_credentials");
-    body.append("scope", scope);
-    const response = await execute({
-      datacenterId,
+    const config = {
+      datacenterId: connectionOptions.datacenterId,
       route,
       headers,
       body,
-      timeout
+      timeout: connectionOptions.timeout
+    };
+    const response = await execute(config);
+    const result = safeParseCreateDistributionResponse(response);
+    return result;
+  } catch (error) {
+    const message = getErrorMessage(error);
+    return failure(message);
+  }
+};
+
+// src/methods/createMailingList.ts
+var createMailingList = (connectionOptions) => async ({
+  directoryId,
+  name,
+  ownerId,
+  prioritizeListMetadata = false,
+  bearerToken = void 0
+}) => {
+  const route = `/API/v3/directories/${directoryId}/mailinglists`;
+  try {
+    const headers = getAuthHeaders(connectionOptions.apiToken, bearerToken);
+    const body = JSON.stringify({
+      name,
+      ownerId,
+      prioritizeListMetadata
     });
-    const result = safeParseBearerToken(response);
+    const config = {
+      datacenterId: connectionOptions.datacenterId,
+      route,
+      headers,
+      body,
+      timeout: connectionOptions.timeout
+    };
+    const response = await execute(config);
+    const result = safeParseCreateMailingListResponse(response);
     return result;
   } catch (error) {
     const message = getErrorMessage(error);
@@ -168,19 +205,45 @@ var getBearerToken = (connectionOptions) => async ({ clientId, clientSecret, sco
   }
 };
 
-// src/methods/getResponseExportProgress.ts
-var getResponseExportProgress = (connectionOptions) => async ({ exportProgressId, surveyId, bearerToken }) => {
-  const route = `/API/v3/surveys/${surveyId}/export-responses/${exportProgressId}`;
+// src/methods/distributions/createReminder.ts
+var createReminder = (connectionOptions) => async ({
+  distributionId,
+  libraryId,
+  messageId,
+  fromEmail,
+  replyToEmail,
+  fromName,
+  subject,
+  embeddedData,
+  sendDate,
+  bearerToken = void 0
+}) => {
+  const route = `/API/v3/distributions/${distributionId}/reminders`;
   try {
     const headers = getAuthHeaders(connectionOptions.apiToken, bearerToken);
+    const body = JSON.stringify({
+      message: {
+        libraryId,
+        messageId
+      },
+      header: {
+        fromEmail,
+        replyToEmail,
+        fromName,
+        subject
+      },
+      embeddedData,
+      sendDate
+    });
     const config = {
       datacenterId: connectionOptions.datacenterId,
       route,
       headers,
+      body,
       timeout: connectionOptions.timeout
     };
     const response = await execute(config);
-    const result = safeParseFileProgressResponse(response);
+    const result = safeParseCreateReminderResponse(response);
     return result;
   } catch (error) {
     const message = getErrorMessage(error);
@@ -188,26 +251,201 @@ var getResponseExportProgress = (connectionOptions) => async ({ exportProgressId
   }
 };
 
-// src/methods/getResponseExportFile.ts
-var getResponseExportFile = (connectionOptions) => async ({ surveyId, fileId, bearerToken }) => {
-  const route = `/API/v3/surveys/${surveyId}/export-responses/${fileId}/file`;
+// src/utils/poll.ts
+async function poll({
+  fn,
+  validate,
+  interval,
+  maxAttempts
+}) {
+  let attempts = 0;
+  const executePoll = async (resolve, reject) => {
+    try {
+      const result = await fn();
+      attempts++;
+      if (validate(result)) {
+        return resolve(result);
+      } else if (maxAttempts && attempts === maxAttempts) {
+        return reject(new Error("Exceeded max attempts"));
+      } else {
+        setTimeout(executePoll, interval, resolve, reject);
+      }
+    } catch (error) {
+      reject(new Error(`Poll function execution failed: ${error}`));
+    }
+  };
+  return new Promise(executePoll);
+}
+
+// src/methods/contacts/startContactsImport.ts
+var startContactsImport = (connectionOptions) => async (options) => {
+  const { directoryId, mailingListId, contacts, transactionMeta, bearerToken } = options;
+  const route = `/API/v3
+/directories/${directoryId}/mailinglists/${mailingListId}/transactioncontacts`;
   try {
     const headers = getAuthHeaders(connectionOptions.apiToken, bearerToken);
+    const body = JSON.stringify({
+      transactionMeta,
+      contacts
+    });
     const config = {
       datacenterId: connectionOptions.datacenterId,
       route,
       headers,
+      body,
       timeout: connectionOptions.timeout
     };
     const response = await execute(config);
-    return response;
+    const result = safeParseStartContactsImportResponse(response);
+    return result;
+  } catch (error) {
+    const message = getErrorMessage(error);
+    return failure(message);
+  }
+};
+
+// src/methods/contacts/getContactsImportStatus.ts
+var getContactsImportStatus = (connectionOptions) => async ({ directoryId, importId, mailingListId, bearerToken = void 0 }) => {
+  const route = `/API/v3
+/directories/${directoryId}/mailinglists/${mailingListId}/transactioncontacts/${importId}`;
+  try {
+    const headers = getAuthHeaders(connectionOptions.apiToken, bearerToken);
+    const config = {
+      datacenterId: connectionOptions.datacenterId,
+      route,
+      headers,
+      timeout: connectionOptions.timeout
+    };
+    const response = await execute(config);
+    const result = safeParseContactsImportStatus(response);
+    return result;
   } catch (error) {
     const message = getErrorMessage(error);
     return failure(message);
   }
 };
 
-// src/methods/startResponseExport.ts
+// src/methods/contacts/getContactsImportSummary.ts
+var getContactsImportSummary = (connectionOptions) => async ({ directoryId, importId, mailingListId, bearerToken = void 0 }) => {
+  const route = `/API/v3
+/directories/${directoryId}/mailinglists/${mailingListId}/transactioncontacts/${importId}/summary`;
+  try {
+    const headers = getAuthHeaders(connectionOptions.apiToken, bearerToken);
+    const config = {
+      datacenterId: connectionOptions.datacenterId,
+      route,
+      headers,
+      timeout: connectionOptions.timeout
+    };
+    const response = await execute(config);
+    const result = safeParseContactsImportSummary(response);
+    return result;
+  } catch (error) {
+    const message = getErrorMessage(error);
+    return failure(message);
+  }
+};
+
+// src/methods/contacts/importContacts.ts
+var importContacts = (connectionOptions) => async (importOptions) => {
+  try {
+    const startImportAction = startContactsImport(connectionOptions);
+    const startResponse = await startImportAction(importOptions);
+    if (!startResponse.success)
+      return failure(startResponse.error);
+    const importProgressAction = getContactsImportStatus(connectionOptions);
+    const progressResponse = await poll({
+      fn: async () => await importProgressAction({
+        directoryId: importOptions.directoryId,
+        importId: startResponse.data.id,
+        mailingListId: importOptions.mailingListId,
+        bearerToken: importOptions.bearerToken
+      }),
+      validate: (res) => res.success && res.data.percentComplete === 100,
+      interval: 1,
+      maxAttempts: 60
+    });
+    if (!progressResponse.success)
+      return failure(progressResponse.error);
+    const getContactImportSummaryAction = getContactsImportSummary(connectionOptions);
+    const fileResponse = await getContactImportSummaryAction({
+      directoryId: importOptions.directoryId,
+      importId: startResponse.data.id,
+      mailingListId: importOptions.mailingListId,
+      bearerToken: importOptions.bearerToken
+    });
+    return fileResponse;
+  } catch (error) {
+    const message = getErrorMessage(error);
+    return failure(message);
+  }
+};
+
+// src/methods/distributions/distributeSurveys.ts
+var distributeSurveys = (connectionOptions) => async (options) => {
+  try {
+    const createMailingListAction = createMailingList(connectionOptions);
+    const startResponse = await createMailingListAction({
+      directoryId: options.directoryId,
+      name: options.mailingListName,
+      ownerId: options.ownerId,
+      prioritizeListMetadata: options.prioritizeListMetadata,
+      bearerToken: options.bearerToken
+    });
+    if (!startResponse.success)
+      return failure(startResponse.error);
+    const importContactsAction = importContacts(connectionOptions);
+    const importResponse = await importContactsAction({
+      directoryId: options.directoryId,
+      mailingListId: startResponse.data,
+      contacts: options.contacts,
+      transactionMeta: options.transactionMeta,
+      bearerToken: options.bearerToken
+    });
+    if (!importResponse.success)
+      return failure(importResponse.error);
+    const createDistributionAction = createDistribution(connectionOptions);
+    const distributionResponse = await createDistributionAction({
+      libraryId: options.libraryId,
+      messageId: options.distributionMessageId,
+      messageText: options.distributionMessageText,
+      mailingListId: startResponse.data,
+      fromEmail: options.fromEmail,
+      fromName: options.fromName,
+      replyToEmail: options.replyToEmail,
+      subject: options.subject,
+      surveyId: options.surveyId,
+      expirationDate: options.expirationDate,
+      type: options.type,
+      embeddedData: options.embeddedData,
+      sendDate: options.sendDate,
+      bearerToken: options.bearerToken
+    });
+    if (!distributionResponse.success)
+      return failure(distributionResponse.error);
+    const createReminderAction = createReminder(connectionOptions);
+    const reminderResponse = await createReminderAction({
+      distributionId: distributionResponse.data,
+      libraryId: options.libraryId,
+      messageId: options.reminderMessageId,
+      fromEmail: options.fromEmail,
+      fromName: options.fromName,
+      replyToEmail: options.replyToEmail,
+      subject: options.subject,
+      embeddedData: options.embeddedData,
+      sendDate: options.sendDate,
+      bearerToken: options.bearerToken
+    });
+    if (!reminderResponse.success)
+      return failure(reminderResponse.error);
+    return success(reminderResponse.data);
+  } catch (error) {
+    const message = getErrorMessage(error);
+    return failure(message);
+  }
+};
+
+// src/methods/responses/startResponseExport.ts
 var startResponseExport = (connectionOptions) => async ({
   surveyId,
   startDate,
@@ -243,6 +481,193 @@ var startResponseExport = (connectionOptions) => async ({
   }
 };
 
+// src/methods/responses/getResponseExportFile.ts
+var getResponseExportFile = (connectionOptions) => async ({ surveyId, fileId, bearerToken }) => {
+  const route = `/API/v3/surveys/${surveyId}/export-responses/${fileId}/file`;
+  try {
+    const headers = getAuthHeaders(connectionOptions.apiToken, bearerToken);
+    const config = {
+      datacenterId: connectionOptions.datacenterId,
+      route,
+      headers,
+      timeout: connectionOptions.timeout
+    };
+    const response = await execute(config);
+    return response;
+  } catch (error) {
+    const message = getErrorMessage(error);
+    return failure(message);
+  }
+};
+
+// src/methods/responses/getResponseExportProgress.ts
+var getResponseExportProgress = (connectionOptions) => async ({ exportProgressId, surveyId, bearerToken }) => {
+  const route = `/API/v3/surveys/${surveyId}/export-responses/${exportProgressId}`;
+  try {
+    const headers = getAuthHeaders(connectionOptions.apiToken, bearerToken);
+    const config = {
+      datacenterId: connectionOptions.datacenterId,
+      route,
+      headers,
+      timeout: connectionOptions.timeout
+    };
+    const response = await execute(config);
+    const result = safeParseFileProgressResponse(response);
+    return result;
+  } catch (error) {
+    const message = getErrorMessage(error);
+    return failure(message);
+  }
+};
+
+// src/methods/responses/exportResponses.ts
+var exportResponses = (connectionOptions) => async (responseOptions) => {
+  try {
+    const startResponseAction = startResponseExport(connectionOptions);
+    const startResponse = await startResponseAction(responseOptions);
+    if (!startResponse.success)
+      return failure(startResponse.error);
+    const exportProgressAction = getResponseExportProgress(connectionOptions);
+    const progressResponse = await poll({
+      fn: async () => await exportProgressAction({
+        exportProgressId: startResponse.data.progressId,
+        surveyId: responseOptions.surveyId,
+        bearerToken: responseOptions.bearerToken
+      }),
+      validate: (res) => res.success && res.data.percentComplete === 100,
+      interval: 1,
+      maxAttempts: 60
+    });
+    if (!progressResponse.success)
+      return failure(progressResponse.error);
+    const getFileResponseAction = getResponseExportFile(connectionOptions);
+    const fileResponse = await getFileResponseAction({
+      surveyId: responseOptions.surveyId,
+      fileId: progressResponse.data.fileId,
+      bearerToken: responseOptions.bearerToken
+    });
+    return fileResponse;
+  } catch (error) {
+    const message = getErrorMessage(error);
+    return failure(message);
+  }
+};
+
+// src/methods/getBearerToken.ts
+var getBearerToken = (connectionOptions) => async ({ clientId, clientSecret, scope }) => {
+  const route = `/oauth2/token`;
+  try {
+    const { datacenterId, timeout } = connectionOptions;
+    const headers = new Headers({
+      Authorization: "Basic " + Buffer.from(`${clientId}:${clientSecret}`).toString("base64")
+    });
+    const body = new FormData();
+    body.append("grant_type", "client_credentials");
+    body.append("scope", scope);
+    const response = await execute({
+      datacenterId,
+      route,
+      headers,
+      body,
+      timeout
+    });
+    const result = safeParseBearerToken(response);
+    return result;
+  } catch (error) {
+    const message = getErrorMessage(error);
+    return failure(message);
+  }
+};
+
+// src/methods/distributions/getDistribution.ts
+var getDistribution = (connectionOptions) => async ({ distributionId, surveyId, bearerToken = void 0 }) => {
+  try {
+    const headers = getAuthHeaders(connectionOptions.apiToken, bearerToken);
+    const qs = new URLSearchParams({ surveyId });
+    const route = `/API/v3/distributions/${distributionId}?${qs.toString()}`;
+    const config = {
+      datacenterId: connectionOptions.datacenterId,
+      route,
+      headers,
+      timeout: connectionOptions.timeout
+    };
+    const response = await execute(config);
+    const result = safeParseGetDistribution(response);
+    return result;
+  } catch (error) {
+    const message = getErrorMessage(error);
+    return failure(message);
+  }
+};
+
+// src/methods/distributions/listDistributions.ts
+var listDistributions = (connectionOptions) => async ({
+  surveyId,
+  distributionRequestType,
+  mailingListId,
+  sendStartDate,
+  sendEndDate,
+  skipToken,
+  useNewPaginationScheme,
+  pageSize,
+  bearerToken = void 0
+}) => {
+  try {
+    const headers = getAuthHeaders(connectionOptions.apiToken, bearerToken);
+    const qs = new URLSearchParams({
+      surveyId,
+      distributionRequestType,
+      mailingListId,
+      sendStartDate: sendStartDate.toISOString(),
+      sendEndDate: sendEndDate.toISOString()
+    });
+    if (skipToken)
+      qs.append("skipToken", skipToken);
+    if (useNewPaginationScheme)
+      qs.append("useNewPaginationScheme", useNewPaginationScheme.toString());
+    if (pageSize)
+      qs.append("pageSize", pageSize.toString());
+    const route = `/API/v3/distributions?${qs.toString()}`;
+    const config = {
+      datacenterId: connectionOptions.datacenterId,
+      route,
+      headers,
+      timeout: connectionOptions.timeout
+    };
+    const response = await execute(config);
+    const result = safeParseListDistributions(response);
+    return result;
+  } catch (error) {
+    const message = getErrorMessage(error);
+    return failure(message);
+  }
+};
+
+// src/methods/listLibraryMessages.ts
+var listLibraryMessages = (connectionOptions) => async ({ libraryId, category, offset, bearerToken = void 0 }) => {
+  const route = `/API/v3/libraries/${libraryId}/messages`;
+  try {
+    const headers = getAuthHeaders(connectionOptions.apiToken, bearerToken);
+    const qs = new URLSearchParams();
+    if (category)
+      qs.append("category", category);
+    if (offset)
+      qs.append("offset", offset.toString());
+    const config = {
+      datacenterId: connectionOptions.datacenterId,
+      route: qs.size > 0 ? route + "?" + qs.toString() : route,
+      headers,
+      timeout: connectionOptions.timeout
+    };
+    const response = await execute(config);
+    const result = safeParseListLibraryMessages(response);
+    return result;
+  } catch (error) {
+    const message = getErrorMessage(error);
+    return failure(message);
+  }
+};
+
 // src/methods/testConnection.ts
 var testConnection = (connectionOptions) => async (bearerToken) => {
   const route = "/API/v3/whoami";
@@ -265,19 +690,41 @@ var testConnection = (connectionOptions) => async (bearerToken) => {
 
 // src/createConnection.ts
 var createConnection = (options) => ({
+  createDistribution: createDistribution(options),
+  createMailingList: createMailingList(options),
+  createReminder: createReminder(options),
+  distributeSurveys: distributeSurveys(options),
   exportResponses: exportResponses(options),
   getBearerToken: getBearerToken(options),
+  getContactsImportStatus: getContactsImportStatus(options),
+  getContactsImportSummary: getContactsImportSummary(options),
+  getDistribution: getDistribution(options),
   getResponseExportFile: getResponseExportFile(options),
   getResponseExportProgress: getResponseExportProgress(options),
+  importContacts: importContacts(options),
+  listDistributions: listDistributions(options),
+  listLibraryMessages: listLibraryMessages(options),
+  startContactsImport: startContactsImport(options),
   startResponseExport: startResponseExport(options),
   testConnection: testConnection(options)
 });
 export {
   createConnection,
+  createDistribution,
+  createMailingList,
+  createReminder,
+  distributeSurveys,
   exportResponses,
   getBearerToken,
+  getContactsImportStatus,
+  getContactsImportSummary,
+  getDistribution,
   getResponseExportFile,
   getResponseExportProgress,
+  importContacts,
+  listDistributions,
+  listLibraryMessages,
+  startContactsImport,
   startResponseExport,
   testConnection
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@b-jones-rfd/qualtrics-api-tasks",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Perform common tasks using the Qualtrics API",
   "private": false,
   "main": "./dist/index.js",