@b-jones-rfd/qualtrics-api-tasks 0.0.5 → 0.1.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @b-jones-rfd/qualtrics-api-tasks
 
+## 0.1.0
+
+### Minor Changes
+
+- efa27c7: Implemented survey file response methods
+
 ## 0.0.5
 
 ### Patch Changes

package/README.md

@@ -139,23 +139,112 @@ export type Action<TConfig, TResponse> = (
 
 If using the actions directly call the factory method with a ConnectionOptions object to return an action that can be used to execute a Qualtrics action.
 
-#### getBearerToken()
+#### exportResponses(options)
+
+Implements [Survey Response File Export](https://api.qualtrics.com/u9e5lh4172v0v-survey-response-export-guide) multistep process.
+
+`options`
+
+| Property                        | Type     | Description                                 | Required | Default |
+| ------------------------------- | -------- | ------------------------------------------- | -------- | ------- |
+| surveyId                        | string   | Quatrics Survey ID                          | Y        |         |
+| startDate                       | Date     | Export start date and time                  | Y        |         |
+| endDate                         | Date     | Export end date and time                    | Y        |         |
+| format                          | Enum     | File format                                 | N        | 'csv'   |
+| breakoutSets                    | boolean  | Split multi-value fields into columns       | N        | true    |
+| compress                        | boolean  | Compress final export                       | N        | true    |
+| exportResponsesInProgress       | boolean  | Only export not complete                    | N        | false   |
+| filterId                        | string   | Return responses matching id                | N        |         |
+| formatDecimalAsComma            | boolean  | Use comma as decimal separator              | N        | false   |
+| includeDisplayOrder             | boolean  | Include display order in export             | N        | false   |
+| limit                           | number   | Max responses to export                     | N        |         |
+| multiselectSeenUnansweredRecode | number   | Recode seen, but unanswered for multiselect | N        |         |
+| newlineReplacement              | string   | Replace newline character with this         | N        |         |
+| seenUnansweredRecode            | number   | Recode seen, but unanswered with this       | N        |         |
+| timeZone                        | string   | Timezone used to determine response date    | N        | 'UTC"   |
+| useLabels                       | boolean  | Export text of answer choice                | N        | false   |
+| embeddedDataIds                 | string[] | Only export these embedded data fields      | N        |         |
+| questionIds                     | string[] | Only export these question IDs              | N        |         |
+| surveyMetadataIds               | string[] | Only export these metadata fields           | N        |         |
+| continuationToken               | string   | Previous export continuation token          | N        |         |
+| allowContinuation               | boolean  | Request continuation token                  | N        | false   |
+| includeLabelColumns             | boolean  | Export two columns, recode and labels       | N        | false   |
+| sortByLastModifiedDate          | boolean  | Sort responses by modified date             | N        | false   |
+| bearerToken                     | string   | Valid Bearer Token                          | N        |         |
+
+#### getBearerToken(options)
 
 Implements [OAuth Authentication (Client Credentials)](https://api.qualtrics.com/9398592961ced-o-auth-authentication-client-credentials)
 
 `options`
 
-| Property     | Type   | Description               | Required |
-| ------------ | ------ | ------------------------- | -------- |
-| clientId     | string | Quatrics Client ID        | Y        |
-| clientSecret | string | Qualtrics Client Password | Y        |
+| Property     | Type   | Description                       | Required |
+| ------------ | ------ | --------------------------------- | -------- |
+| clientId     | string | Quatrics Client ID                | Y        |
+| clientSecret | string | Qualtrics Client Password         | Y        |
+| scope        | string | Qualtrics Client requested scopes | Y        |
+
+#### getResponseExportFile(options)
 
-#### testConnection(options)
+Implements [Get Response Export File](https://api.qualtrics.com/41296b6f2e828-get-response-export-file)
 
 `options`
 
 | Property    | Type   | Description        | Required |
 | ----------- | ------ | ------------------ | -------- |
+| surveyId    | string | Quatrics Survey ID | Y        |
+| fileId      | string | File ID            | Y        |
+| bearerToken | string | Valid Bearer Token | N        |
+
+#### getResponseExportProgress(options)
+
+Implements [Get Response Export Progress](https://api.qualtrics.com/37e6a66f74ab4-get-response-export-progress)
+
+`options`
+
+| Property         | Type   | Description        | Required |
+| ---------------- | ------ | ------------------ | -------- |
+| surveyId         | string | Quatrics Survey ID | Y        |
+| exportProgressId | string | Progress ID        | Y        |
+| bearerToken      | string | Valid Bearer Token | N        |
+
+#### startResponseExports(options)
+
+Implements [Start Response Exports](https://api.qualtrics.com/6b00592b9c013-start-response-export)
+
+`options`
+
+| Property                        | Type     | Description                                 | Required | Default |
+| ------------------------------- | -------- | ------------------------------------------- | -------- | ------- |
+| surveyId                        | string   | Quatrics Survey ID                          | Y        |         |
+| startDate                       | Date     | Export start date and time                  | Y        |         |
+| endDate                         | Date     | Export end date and time                    | Y        |         |
+| format                          | Enum     | File format                                 | N        | 'csv'   |
+| breakoutSets                    | boolean  | Split multi-value fields into columns       | N        | true    |
+| compress                        | boolean  | Compress final export                       | N        | true    |
+| exportResponsesInProgress       | boolean  | Only export not complete                    | N        | false   |
+| filterId                        | string   | Return responses matching id                | N        |         |
+| formatDecimalAsComma            | boolean  | Use comma as decimal separator              | N        | false   |
+| includeDisplayOrder             | boolean  | Include display order in export             | N        | false   |
+| limit                           | number   | Max responses to export                     | N        |         |
+| multiselectSeenUnansweredRecode | number   | Recode seen, but unanswered for multiselect | N        |         |
+| newlineReplacement              | string   | Replace newline character with this         | N        |         |
+| seenUnansweredRecode            | number   | Recode seen, but unanswered with this       | N        |         |
+| timeZone                        | string   | Timezone used to determine response date    | N        | 'UTC"   |
+| useLabels                       | boolean  | Export text of answer choice                | N        | false   |
+| embeddedDataIds                 | string[] | Only export these embedded data fields      | N        |         |
+| questionIds                     | string[] | Only export these question IDs              | N        |         |
+| surveyMetadataIds               | string[] | Only export these metadata fields           | N        |         |
+| continuationToken               | string   | Previous export continuation token          | N        |         |
+| allowContinuation               | boolean  | Request continuation token                  | N        | false   |
+| includeLabelColumns             | boolean  | Export two columns, recode and labels       | N        | false   |
+| sortByLastModifiedDate          | boolean  | Sort responses by modified date             | N        | false   |
+| bearerToken                     | string   | Valid Bearer Token                          | N        |         |
+
+#### testConnection(bearerToken)
+
+| Parameter   | Type   | Description        | Required |
+| ----------- | ------ | ------------------ | -------- |
 | bearerToken | string | Valid Bearer Token | N        |
 
 ## Responses
@@ -196,4 +285,4 @@ We use [SemVer](http://semver.org/) for versioning. For the versions available,
 
 ## License
 
-[MIT License](https://github.com/B-Jones-RFD/sp-rest-connect/blob/main/LICENSE)
+[MIT License](https://github.com/B-Jones-RFD/qualtrics-api-tasks/blob/main/LICENSE)

package/dist/index.d.mts

@@ -7,6 +7,7 @@ type Failure = {
     error: string;
 };
 type Result<T> = Success<T> | Failure;
+type ResponseFormat = 'csv' | 'json' | 'ndjson' | 'spss' | 'tsv' | 'xml';
 type Action<TConfig, TResponse> = (options: TConfig) => Promise<Result<TResponse>>;
 type ConnectionOptions = {
     datacenterId: string;
@@ -15,21 +16,88 @@ type ConnectionOptions = {
 };
 type ActionFactory<TParams, TResponse> = (options: ConnectionOptions) => Action<TParams, TResponse>;
 type Connection = {
-    testConnection: Action<string | undefined, void>;
+    exportResponses: Action<ExportResponsesOptions, Buffer>;
     getBearerToken: Action<{
         clientId: string;
         clientSecret: string;
+        scope: string;
     }, string>;
+    getResponseExportProgress: Action<{
+        exportProgressId: string;
+        surveyId: string;
+        bearerToken?: string;
+    }, FileProgressResponse>;
+    startResponseExport: Action<ExportResponsesOptions, {
+        progressId: string;
+        percentComplete: number;
+        status: string;
+        continuationToken?: string;
+    }>;
+    testConnection: (bearerToken?: string) => Promise<Result<void>>;
 };
 type ConnectionFactory = (options: ConnectionOptions) => Connection;
+type ExportResponsesOptions = {
+    surveyId: string;
+    startDate: Date;
+    endDate: Date;
+    format?: ResponseFormat;
+    breakoutSets?: boolean;
+    compress?: boolean;
+    exportResponsesInProgress?: boolean;
+    filterId?: string;
+    formatDecimalAsComma?: boolean;
+    includeDisplayOrder?: boolean;
+    limit?: number;
+    multiselectSeenUnansweredRecode?: number;
+    newlineReplacement?: string;
+    seenUnansweredRecode?: number;
+    timeZone?: string;
+    useLabels?: boolean;
+    embeddedDataIds?: string[];
+    questionIds?: string[];
+    surveyMetadataIds?: string[];
+    continuationToken?: string;
+    allowContinuation?: boolean;
+    includeLabelColumns?: boolean;
+    sortByLastModifiedDate?: boolean;
+    bearerToken?: string;
+};
+type FileProgressResponse = {
+    fileId: string;
+    percentComplete: number;
+    status: string;
+    continuationToken?: string;
+};
 
 declare const createConnection: ConnectionFactory;
 
+declare const exportResponses: ActionFactory<ExportResponsesOptions, Buffer>;
+
 declare const getBearerToken: ActionFactory<{
     clientId: string;
     clientSecret: string;
+    scope: string;
 }, string>;
 
-declare const testConnection: ActionFactory<string | undefined, void>;
+declare const getResponseExportProgress: ActionFactory<{
+    exportProgressId: string;
+    surveyId: string;
+    bearerToken?: string;
+}, FileProgressResponse>;
+
+declare const getResponseExportFile: ActionFactory<{
+    surveyId: string;
+    fileId: string;
+    bearerToken?: string;
+}, Buffer>;
+
+declare const startResponseExport: ActionFactory<ExportResponsesOptions, {
+    progressId: string;
+    percentComplete: number;
+    status: string;
+    continuationToken?: string;
+}>;
+
+declare const testConnection: (connectionOptions: ConnectionOptions) => (bearerToken?: string) => Promise<Result<void>>;
 
-export { type Action, type ActionFactory, type Connection, type ConnectionFactory, type ConnectionOptions, type Failure, type Result, type Success, createConnection, getBearerToken, testConnection };
+export { type Action, type ActionFactory, type Connection, type ConnectionFactory, type ConnectionOptions, type ExportResponsesOptions, type Failure, type FileProgressResponse, type ResponseFormat, type Result, type Success, createConnection, exportResponses, getBearerToken, getResponseExportFile, getResponseExportProgress, startResponseExport, testConnection };

package/dist/index.d.ts

@@ -7,6 +7,7 @@ type Failure = {
     error: string;
 };
 type Result<T> = Success<T> | Failure;
+type ResponseFormat = 'csv' | 'json' | 'ndjson' | 'spss' | 'tsv' | 'xml';
 type Action<TConfig, TResponse> = (options: TConfig) => Promise<Result<TResponse>>;
 type ConnectionOptions = {
     datacenterId: string;
@@ -15,21 +16,88 @@ type ConnectionOptions = {
 };
 type ActionFactory<TParams, TResponse> = (options: ConnectionOptions) => Action<TParams, TResponse>;
 type Connection = {
-    testConnection: Action<string | undefined, void>;
+    exportResponses: Action<ExportResponsesOptions, Buffer>;
     getBearerToken: Action<{
         clientId: string;
         clientSecret: string;
+        scope: string;
     }, string>;
+    getResponseExportProgress: Action<{
+        exportProgressId: string;
+        surveyId: string;
+        bearerToken?: string;
+    }, FileProgressResponse>;
+    startResponseExport: Action<ExportResponsesOptions, {
+        progressId: string;
+        percentComplete: number;
+        status: string;
+        continuationToken?: string;
+    }>;
+    testConnection: (bearerToken?: string) => Promise<Result<void>>;
 };
 type ConnectionFactory = (options: ConnectionOptions) => Connection;
+type ExportResponsesOptions = {
+    surveyId: string;
+    startDate: Date;
+    endDate: Date;
+    format?: ResponseFormat;
+    breakoutSets?: boolean;
+    compress?: boolean;
+    exportResponsesInProgress?: boolean;
+    filterId?: string;
+    formatDecimalAsComma?: boolean;
+    includeDisplayOrder?: boolean;
+    limit?: number;
+    multiselectSeenUnansweredRecode?: number;
+    newlineReplacement?: string;
+    seenUnansweredRecode?: number;
+    timeZone?: string;
+    useLabels?: boolean;
+    embeddedDataIds?: string[];
+    questionIds?: string[];
+    surveyMetadataIds?: string[];
+    continuationToken?: string;
+    allowContinuation?: boolean;
+    includeLabelColumns?: boolean;
+    sortByLastModifiedDate?: boolean;
+    bearerToken?: string;
+};
+type FileProgressResponse = {
+    fileId: string;
+    percentComplete: number;
+    status: string;
+    continuationToken?: string;
+};
 
 declare const createConnection: ConnectionFactory;
 
+declare const exportResponses: ActionFactory<ExportResponsesOptions, Buffer>;
+
 declare const getBearerToken: ActionFactory<{
     clientId: string;
     clientSecret: string;
+    scope: string;
 }, string>;
 
-declare const testConnection: ActionFactory<string | undefined, void>;
+declare const getResponseExportProgress: ActionFactory<{
+    exportProgressId: string;
+    surveyId: string;
+    bearerToken?: string;
+}, FileProgressResponse>;
+
+declare const getResponseExportFile: ActionFactory<{
+    surveyId: string;
+    fileId: string;
+    bearerToken?: string;
+}, Buffer>;
+
+declare const startResponseExport: ActionFactory<ExportResponsesOptions, {
+    progressId: string;
+    percentComplete: number;
+    status: string;
+    continuationToken?: string;
+}>;
+
+declare const testConnection: (connectionOptions: ConnectionOptions) => (bearerToken?: string) => Promise<Result<void>>;
 
-export { type Action, type ActionFactory, type Connection, type ConnectionFactory, type ConnectionOptions, type Failure, type Result, type Success, createConnection, getBearerToken, testConnection };
+export { type Action, type ActionFactory, type Connection, type ConnectionFactory, type ConnectionOptions, type ExportResponsesOptions, type Failure, type FileProgressResponse, type ResponseFormat, type Result, type Success, createConnection, exportResponses, getBearerToken, getResponseExportFile, getResponseExportProgress, startResponseExport, testConnection };

package/dist/index.js

@@ -21,12 +21,16 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var src_exports = {};
 __export(src_exports, {
   createConnection: () => createConnection,
+  exportResponses: () => exportResponses,
   getBearerToken: () => getBearerToken,
+  getResponseExportFile: () => getResponseExportFile,
+  getResponseExportProgress: () => getResponseExportProgress,
+  startResponseExport: () => startResponseExport,
   testConnection: () => testConnection
 });
 module.exports = __toCommonJS(src_exports);
 
-// src/utils.ts
+// src/utils/index.ts
 function success(data) {
   return {
     success: true,
@@ -42,12 +46,6 @@ function failure(error) {
 function getErrorMessage(error) {
   return error ? typeof error === "object" && "message" in error && typeof error.message === "string" ? error.message : error.toString() : "An error occured";
 }
-function safeParseBearerToken(response) {
-  return response?.access_token && typeof response.access_token === "string" ? success(response.access_token) : failure("Incorrect token format");
-}
-function safeParseTestResponse(response) {
-  return response?.result?.userId ? success(void 0) : failure("Incorrect test response format");
-}
 function getAuthHeaders(apiToken, bearerToken) {
   if (apiToken)
     return new Headers({
@@ -55,7 +53,7 @@ function getAuthHeaders(apiToken, bearerToken) {
     });
   if (bearerToken) {
     return new Headers({
-      Authorization: bearerToken
+      Authorization: `Bearer ${bearerToken}`
     });
   }
   throw new Error(
@@ -63,6 +61,82 @@ 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");
+}
+function safeParseTestResponse(response) {
+  return response?.result?.userId ? success(void 0) : failure("Incorrect test response format");
+}
+function safeParseStartFileExportResponse(response) {
+  return "result" in response ? "progressId" in response.result && "percentComplete" in response.result && "status" in response.result ? success(response.result) : failure("Start Export Response invalid format") : "error" in response ? failure(`${response.error.errorCode}: ${response.error.errorMessage}`) : failure(`Unable to parse Start Export 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 safeParseFileResponse(response) {
+  return Buffer.isBuffer(response) ? success(response) : failure("Incorrect file response format");
+}
+
 // src/qualtrics/index.ts
 async function execute(config) {
   const { datacenterId, route, headers, timeout, body } = config;
@@ -94,7 +168,7 @@ async function execute(config) {
 }
 
 // src/methods/getBearerToken.ts
-var getBearerToken = (connectionOptions) => async ({ clientId, clientSecret }) => {
+var getBearerToken = (connectionOptions) => async ({ clientId, clientSecret, scope }) => {
   const route = `/oauth2/token`;
   try {
     const { datacenterId, timeout } = connectionOptions;
@@ -103,7 +177,7 @@ var getBearerToken = (connectionOptions) => async ({ clientId, clientSecret }) =
     });
     const body = new FormData();
     body.append("grant_type", "client_credentials");
-    body.append("scope", "manage:all");
+    body.append("scope", scope);
     const response = await execute({
       datacenterId,
       route,
@@ -119,6 +193,80 @@ var getBearerToken = (connectionOptions) => async ({ clientId, clientSecret }) =
   }
 };
 
+// src/methods/getResponseExportProgress.ts
+var getResponseExportProgress = (connectionOptions) => async ({ exportProgressId, surveyId, bearerToken }) => {
+  const route = `/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/getResponseExportFile.ts
+var getResponseExportFile = (connectionOptions) => async ({ surveyId, fileId, bearerToken }) => {
+  const route = `/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);
+    const result = safeParseFileResponse(response);
+    return result;
+  } catch (error) {
+    const message = getErrorMessage(error);
+    return failure(message);
+  }
+};
+
+// src/methods/startResponseExport.ts
+var startResponseExport = (connectionOptions) => async ({
+  surveyId,
+  startDate,
+  endDate,
+  format = "csv",
+  bearerToken = void 0,
+  ...rest
+}) => {
+  const route = `/surveys/${surveyId}/export-responses`;
+  try {
+    const headers = getAuthHeaders(connectionOptions.apiToken, bearerToken);
+    const body = JSON.stringify({
+      startDate: startDate.toISOString(),
+      endDate: endDate.toDateString(),
+      format,
+      ...rest
+    });
+    const config = {
+      datacenterId: connectionOptions.datacenterId,
+      route,
+      headers,
+      body,
+      timeout: connectionOptions.timeout
+    };
+    const response = await execute(config);
+    const result = safeParseStartFileExportResponse(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";
@@ -141,12 +289,19 @@ var testConnection = (connectionOptions) => async (bearerToken) => {
 
 // src/createConnection.ts
 var createConnection = (options) => ({
-  testConnection: testConnection(options),
-  getBearerToken: getBearerToken(options)
+  exportResponses: exportResponses(options),
+  getBearerToken: getBearerToken(options),
+  getResponseExportProgress: getResponseExportProgress(options),
+  startResponseExport: startResponseExport(options),
+  testConnection: testConnection(options)
 });
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   createConnection,
+  exportResponses,
   getBearerToken,
+  getResponseExportFile,
+  getResponseExportProgress,
+  startResponseExport,
   testConnection
 });

package/dist/index.mjs

@@ -1,4 +1,4 @@
-// src/utils.ts
+// src/utils/index.ts
 function success(data) {
   return {
     success: true,
@@ -14,12 +14,6 @@ function failure(error) {
 function getErrorMessage(error) {
   return error ? typeof error === "object" && "message" in error && typeof error.message === "string" ? error.message : error.toString() : "An error occured";
 }
-function safeParseBearerToken(response) {
-  return response?.access_token && typeof response.access_token === "string" ? success(response.access_token) : failure("Incorrect token format");
-}
-function safeParseTestResponse(response) {
-  return response?.result?.userId ? success(void 0) : failure("Incorrect test response format");
-}
 function getAuthHeaders(apiToken, bearerToken) {
   if (apiToken)
     return new Headers({
@@ -27,7 +21,7 @@ function getAuthHeaders(apiToken, bearerToken) {
     });
   if (bearerToken) {
     return new Headers({
-      Authorization: bearerToken
+      Authorization: `Bearer ${bearerToken}`
     });
   }
   throw new Error(
@@ -35,6 +29,82 @@ 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");
+}
+function safeParseTestResponse(response) {
+  return response?.result?.userId ? success(void 0) : failure("Incorrect test response format");
+}
+function safeParseStartFileExportResponse(response) {
+  return "result" in response ? "progressId" in response.result && "percentComplete" in response.result && "status" in response.result ? success(response.result) : failure("Start Export Response invalid format") : "error" in response ? failure(`${response.error.errorCode}: ${response.error.errorMessage}`) : failure(`Unable to parse Start Export 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 safeParseFileResponse(response) {
+  return Buffer.isBuffer(response) ? success(response) : failure("Incorrect file response format");
+}
+
 // src/qualtrics/index.ts
 async function execute(config) {
   const { datacenterId, route, headers, timeout, body } = config;
@@ -66,7 +136,7 @@ async function execute(config) {
 }
 
 // src/methods/getBearerToken.ts
-var getBearerToken = (connectionOptions) => async ({ clientId, clientSecret }) => {
+var getBearerToken = (connectionOptions) => async ({ clientId, clientSecret, scope }) => {
   const route = `/oauth2/token`;
   try {
     const { datacenterId, timeout } = connectionOptions;
@@ -75,7 +145,7 @@ var getBearerToken = (connectionOptions) => async ({ clientId, clientSecret }) =
     });
     const body = new FormData();
     body.append("grant_type", "client_credentials");
-    body.append("scope", "manage:all");
+    body.append("scope", scope);
     const response = await execute({
       datacenterId,
       route,
@@ -91,6 +161,80 @@ var getBearerToken = (connectionOptions) => async ({ clientId, clientSecret }) =
   }
 };
 
+// src/methods/getResponseExportProgress.ts
+var getResponseExportProgress = (connectionOptions) => async ({ exportProgressId, surveyId, bearerToken }) => {
+  const route = `/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/getResponseExportFile.ts
+var getResponseExportFile = (connectionOptions) => async ({ surveyId, fileId, bearerToken }) => {
+  const route = `/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);
+    const result = safeParseFileResponse(response);
+    return result;
+  } catch (error) {
+    const message = getErrorMessage(error);
+    return failure(message);
+  }
+};
+
+// src/methods/startResponseExport.ts
+var startResponseExport = (connectionOptions) => async ({
+  surveyId,
+  startDate,
+  endDate,
+  format = "csv",
+  bearerToken = void 0,
+  ...rest
+}) => {
+  const route = `/surveys/${surveyId}/export-responses`;
+  try {
+    const headers = getAuthHeaders(connectionOptions.apiToken, bearerToken);
+    const body = JSON.stringify({
+      startDate: startDate.toISOString(),
+      endDate: endDate.toDateString(),
+      format,
+      ...rest
+    });
+    const config = {
+      datacenterId: connectionOptions.datacenterId,
+      route,
+      headers,
+      body,
+      timeout: connectionOptions.timeout
+    };
+    const response = await execute(config);
+    const result = safeParseStartFileExportResponse(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";
@@ -113,11 +257,18 @@ var testConnection = (connectionOptions) => async (bearerToken) => {
 
 // src/createConnection.ts
 var createConnection = (options) => ({
-  testConnection: testConnection(options),
-  getBearerToken: getBearerToken(options)
+  exportResponses: exportResponses(options),
+  getBearerToken: getBearerToken(options),
+  getResponseExportProgress: getResponseExportProgress(options),
+  startResponseExport: startResponseExport(options),
+  testConnection: testConnection(options)
 });
 export {
   createConnection,
+  exportResponses,
   getBearerToken,
+  getResponseExportFile,
+  getResponseExportProgress,
+  startResponseExport,
   testConnection
 };

package/package.json

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

package/tests/utils.test.ts

@@ -1,10 +1,12 @@
 import { describe, it, expect } from 'vitest'
+import { success, failure } from '../src/utils'
 import {
-  success,
-  failure,
   safeParseBearerToken,
   safeParseTestResponse,
-} from '../src/utils'
+  safeParseStartFileExportResponse,
+  safeParseFileProgressResponse,
+  safeParseFileResponse,
+} from '../src/utils/parsers'
 
 describe('safeParseBearerToken', () => {
   const fixture = {
@@ -29,6 +31,92 @@ describe('safeParseBearerToken', () => {
   })
 })
 
+describe('safeParseFileProgressResponse', () => {
+  const fixture = {
+    result: {
+      fileId: 'sometoken',
+      percentComplete: 0,
+      status: 'inProgress',
+    },
+  }
+
+  it('should pass with correct data', () => {
+    const res = fixture
+    const expected = success(fixture.result)
+    const parsed = safeParseFileProgressResponse(res)
+    expect(parsed).toStrictEqual(expected)
+  })
+
+  it('should fail when error response', () => {
+    const res = {
+      error: {
+        errorCode: '401',
+        errorMessage: 'Some error',
+      },
+    }
+    const expected = failure(
+      `${res.error.errorCode}: ${res.error.errorMessage}`
+    )
+    const parsed = safeParseFileProgressResponse(res)
+    expect(parsed).toStrictEqual(expected)
+  })
+
+  it('should fail with missing props', () => {
+    const res = {
+      result: {
+        percentComplete: 0,
+        status: 'inProgress',
+      },
+    }
+    const expected = failure('File Progress Response invalid format')
+    const parsed = safeParseFileProgressResponse(res)
+    expect(parsed).toStrictEqual(expected)
+  })
+})
+
+describe('safeParseStartFileExportResponse', () => {
+  const fixture = {
+    result: {
+      progressId: 'sometoken',
+      percentComplete: 0,
+      status: 'inProgress',
+    },
+  }
+
+  it('should pass with correct data', () => {
+    const res = fixture
+    const expected = success(fixture.result)
+    const parsed = safeParseStartFileExportResponse(res)
+    expect(parsed).toStrictEqual(expected)
+  })
+
+  it('should fail when error response', () => {
+    const res = {
+      error: {
+        errorCode: '401',
+        errorMessage: 'Some error',
+      },
+    }
+    const expected = failure(
+      `${res.error.errorCode}: ${res.error.errorMessage}`
+    )
+    const parsed = safeParseStartFileExportResponse(res)
+    expect(parsed).toStrictEqual(expected)
+  })
+
+  it('should fail with missing props', () => {
+    const res = {
+      result: {
+        percentComplete: 0,
+        status: 'inProgress',
+      },
+    }
+    const expected = failure('Start Export Response invalid format')
+    const parsed = safeParseStartFileExportResponse(res)
+    expect(parsed).toStrictEqual(expected)
+  })
+})
+
 describe('safeParseTestResponse', () => {
   const fixture = {
     result: {
@@ -52,3 +140,21 @@ describe('safeParseTestResponse', () => {
     expect(parsed).toStrictEqual(expected)
   })
 })
+
+describe('safeParseFileResponse', () => {
+  const fixture = Buffer.from('file content')
+
+  it('should pass with correct data', () => {
+    const res = fixture
+    const expected = success(fixture)
+    const parsed = safeParseFileResponse(res)
+    expect(parsed).toStrictEqual(expected)
+  })
+
+  it('should fail with invalid response type', () => {
+    const res = { fixture }
+    const expected = failure('Incorrect file response format')
+    const parsed = safeParseFileResponse(res)
+    expect(parsed).toStrictEqual(expected)
+  })
+})