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

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @b-jones-rfd/qualtrics-api-tasks
 
+## 0.2.0
+
+### Minor Changes
+
+- a5028bb: Support file export multiple formats
+
+## 0.1.1
+
+### Patch Changes
+
+- 2f8dbdf: Added JSDoc action method descriptions
+
 ## 0.1.0
 
 ### Minor Changes

package/README.md

@@ -76,7 +76,7 @@ import { createConnection } from '@b-jones-rfd/qualtrics-api-tasks'
 const connectionOptions = {
   datacenterId: 'az1',
   apiToken: 'my API Token', // optional
-  timeout: 20000, // optional timeout in milliseconds, default is 30 seconds
+  timeout: 20 * 1000, // optional timeout in milliseconds, default is 30 seconds
 }
 
 const connection: SiteConnection = createConnection(connectionOptions)
@@ -123,9 +123,9 @@ async function testMyQualtricsConnection(listName: string) {
 
 `timeout`
 
-| Type   | Default value | Description               | Example               | Required |
-| ------ | ------------- | ------------------------- | --------------------- | -------- |
-| number | 30000         | Qualtrics request timeout | sharepoint.domain.com | N        |
+| Type   | Default value | Description               | Example | Required |
+| ------ | ------------- | ------------------------- | ------- | -------- |
+| number | 30000         | Qualtrics request timeout | 1000    | N        |
 
 ### Actions
 

package/dist/index.d.mts

@@ -22,6 +22,11 @@ type Connection = {
         clientSecret: string;
         scope: string;
     }, string>;
+    getResponseExportFile: Action<{
+        surveyId: string;
+        fileId: string;
+        bearerToken?: string;
+    }, Buffer>;
     getResponseExportProgress: Action<{
         exportProgressId: string;
         surveyId: string;
@@ -33,7 +38,7 @@ type Connection = {
         status: string;
         continuationToken?: string;
     }>;
-    testConnection: (bearerToken?: string) => Promise<Result<void>>;
+    testConnection: (bearerToken?: string) => Promise<Result<string>>;
 };
 type ConnectionFactory = (options: ConnectionOptions) => Connection;
 type ExportResponsesOptions = {
@@ -71,26 +76,56 @@ type FileProgressResponse = {
 
 declare const createConnection: ConnectionFactory;
 
+/**
+ * Export Survey Response File
+ *
+ * Implements Survey Response File Export end to end
+ * @see https://api.qualtrics.com/u9e5lh4172v0v-survey-response-export-guide
+ */
 declare const exportResponses: ActionFactory<ExportResponsesOptions, Buffer>;
 
+/**
+ * Get Bearer Token
+ *
+ * Implements OAuth Authentication (Client Credentials
+ * @see https://api.qualtrics.com/9398592961ced-o-auth-authentication-client-credentials
+ */
 declare const getBearerToken: ActionFactory<{
     clientId: string;
     clientSecret: string;
     scope: string;
 }, string>;
 
+/**
+ * Get Response Export File
+ *
+ * Implements Get Response Export Progress.  This is step 2 in the survey response file export process.
+ * @see https://api.qualtrics.com/37e6a66f74ab4-get-response-export-progress
+ */
 declare const getResponseExportProgress: ActionFactory<{
     exportProgressId: string;
     surveyId: string;
     bearerToken?: string;
 }, FileProgressResponse>;
 
+/**
+ * Get Response Export File
+ *
+ * Implements Get Response Export File.  This is step 3 in the survey response file export process.
+ * @see https://api.qualtrics.com/41296b6f2e828-get-response-export-file
+ */
 declare const getResponseExportFile: ActionFactory<{
     surveyId: string;
     fileId: string;
     bearerToken?: string;
 }, Buffer>;
 
+/**
+ *  Start Response Export
+ *
+ * Implements Start Response File Export
+ * @see https://api.qualtrics.com/6b00592b9c013-start-response-export
+ */
 declare const startResponseExport: ActionFactory<ExportResponsesOptions, {
     progressId: string;
     percentComplete: number;
@@ -98,6 +133,9 @@ declare const startResponseExport: ActionFactory<ExportResponsesOptions, {
     continuationToken?: string;
 }>;
 
-declare const testConnection: (connectionOptions: ConnectionOptions) => (bearerToken?: string) => Promise<Result<void>>;
+/**
+ * Test connection to Qualtrics API
+ */
+declare const testConnection: (connectionOptions: ConnectionOptions) => (bearerToken?: string) => Promise<Result<string>>;
 
 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

@@ -22,6 +22,11 @@ type Connection = {
         clientSecret: string;
         scope: string;
     }, string>;
+    getResponseExportFile: Action<{
+        surveyId: string;
+        fileId: string;
+        bearerToken?: string;
+    }, Buffer>;
     getResponseExportProgress: Action<{
         exportProgressId: string;
         surveyId: string;
@@ -33,7 +38,7 @@ type Connection = {
         status: string;
         continuationToken?: string;
     }>;
-    testConnection: (bearerToken?: string) => Promise<Result<void>>;
+    testConnection: (bearerToken?: string) => Promise<Result<string>>;
 };
 type ConnectionFactory = (options: ConnectionOptions) => Connection;
 type ExportResponsesOptions = {
@@ -71,26 +76,56 @@ type FileProgressResponse = {
 
 declare const createConnection: ConnectionFactory;
 
+/**
+ * Export Survey Response File
+ *
+ * Implements Survey Response File Export end to end
+ * @see https://api.qualtrics.com/u9e5lh4172v0v-survey-response-export-guide
+ */
 declare const exportResponses: ActionFactory<ExportResponsesOptions, Buffer>;
 
+/**
+ * Get Bearer Token
+ *
+ * Implements OAuth Authentication (Client Credentials
+ * @see https://api.qualtrics.com/9398592961ced-o-auth-authentication-client-credentials
+ */
 declare const getBearerToken: ActionFactory<{
     clientId: string;
     clientSecret: string;
     scope: string;
 }, string>;
 
+/**
+ * Get Response Export File
+ *
+ * Implements Get Response Export Progress.  This is step 2 in the survey response file export process.
+ * @see https://api.qualtrics.com/37e6a66f74ab4-get-response-export-progress
+ */
 declare const getResponseExportProgress: ActionFactory<{
     exportProgressId: string;
     surveyId: string;
     bearerToken?: string;
 }, FileProgressResponse>;
 
+/**
+ * Get Response Export File
+ *
+ * Implements Get Response Export File.  This is step 3 in the survey response file export process.
+ * @see https://api.qualtrics.com/41296b6f2e828-get-response-export-file
+ */
 declare const getResponseExportFile: ActionFactory<{
     surveyId: string;
     fileId: string;
     bearerToken?: string;
 }, Buffer>;
 
+/**
+ *  Start Response Export
+ *
+ * Implements Start Response File Export
+ * @see https://api.qualtrics.com/6b00592b9c013-start-response-export
+ */
 declare const startResponseExport: ActionFactory<ExportResponsesOptions, {
     progressId: string;
     percentComplete: number;
@@ -98,6 +133,9 @@ declare const startResponseExport: ActionFactory<ExportResponsesOptions, {
     continuationToken?: string;
 }>;
 
-declare const testConnection: (connectionOptions: ConnectionOptions) => (bearerToken?: string) => Promise<Result<void>>;
+/**
+ * Test connection to Qualtrics API
+ */
+declare const testConnection: (connectionOptions: ConnectionOptions) => (bearerToken?: string) => Promise<Result<string>>;
 
 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

@@ -125,7 +125,7 @@ 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");
+  return response?.result?.userId ? success("Connection successful") : 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`);
@@ -133,9 +133,6 @@ 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 safeParseFileResponse(response) {
-  return Buffer.isBuffer(response) ? success(response) : failure("Incorrect file response format");
-}
 
 // src/qualtrics/index.ts
 async function execute(config) {
@@ -149,8 +146,9 @@ async function execute(config) {
     signal: controller.signal
   };
   if (body) {
-    if (typeof body === "string")
+    if (typeof body === "string") {
       headers.append("Content-Type", "application/json");
+    }
     options.method = "POST";
     options.headers = headers;
     options.body = body;
@@ -159,10 +157,19 @@ async function execute(config) {
   const response = await fetch(resource, options);
   clearTimeout(timer);
   if (response.ok) {
-    const data = await response.json();
-    return Promise.resolve(data);
+    const contentType = response.headers.get("content-type");
+    switch (contentType) {
+      case "application/json":
+        return Promise.resolve(await response.json());
+      case "application/csv":
+      case "application/tsv":
+      case "application/xml":
+        return Promise.resolve(await response.text());
+      default:
+        return Promise.resolve(response.body);
+    }
   } else {
-    const message = await response.text();
+    const message = await response.json();
     return Promise.reject(`${response.status}: ${message}`);
   }
 }
@@ -195,7 +202,7 @@ var getBearerToken = (connectionOptions) => async ({ clientId, clientSecret, sco
 
 // src/methods/getResponseExportProgress.ts
 var getResponseExportProgress = (connectionOptions) => async ({ exportProgressId, surveyId, bearerToken }) => {
-  const route = `/surveys/${surveyId}/export-responses/${exportProgressId}`;
+  const route = `/API/v3/surveys/${surveyId}/export-responses/${exportProgressId}`;
   try {
     const headers = getAuthHeaders(connectionOptions.apiToken, bearerToken);
     const config = {
@@ -215,7 +222,7 @@ var getResponseExportProgress = (connectionOptions) => async ({ exportProgressId
 
 // src/methods/getResponseExportFile.ts
 var getResponseExportFile = (connectionOptions) => async ({ surveyId, fileId, bearerToken }) => {
-  const route = `/surveys/${surveyId}/export-responses/${fileId}/file`;
+  const route = `/API/v3/surveys/${surveyId}/export-responses/${fileId}/file`;
   try {
     const headers = getAuthHeaders(connectionOptions.apiToken, bearerToken);
     const config = {
@@ -225,8 +232,7 @@ var getResponseExportFile = (connectionOptions) => async ({ surveyId, fileId, be
       timeout: connectionOptions.timeout
     };
     const response = await execute(config);
-    const result = safeParseFileResponse(response);
-    return result;
+    return response;
   } catch (error) {
     const message = getErrorMessage(error);
     return failure(message);
@@ -242,12 +248,14 @@ var startResponseExport = (connectionOptions) => async ({
   bearerToken = void 0,
   ...rest
 }) => {
-  const route = `/surveys/${surveyId}/export-responses`;
+  const route = `/API/v3/surveys/${surveyId}/export-responses`;
   try {
     const headers = getAuthHeaders(connectionOptions.apiToken, bearerToken);
     const body = JSON.stringify({
-      startDate: startDate.toISOString(),
-      endDate: endDate.toDateString(),
+      startDate: "2024-03-01T06:00:00Z",
+      //startDate.toISOString(),
+      endDate: "2024-03-05T06:00:00Z",
+      //endDate.toISOString(),
       format,
       ...rest
     });
@@ -291,6 +299,7 @@ var testConnection = (connectionOptions) => async (bearerToken) => {
 var createConnection = (options) => ({
   exportResponses: exportResponses(options),
   getBearerToken: getBearerToken(options),
+  getResponseExportFile: getResponseExportFile(options),
   getResponseExportProgress: getResponseExportProgress(options),
   startResponseExport: startResponseExport(options),
   testConnection: testConnection(options)

package/dist/index.mjs

@@ -93,7 +93,7 @@ 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");
+  return response?.result?.userId ? success("Connection successful") : 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`);
@@ -101,9 +101,6 @@ 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 safeParseFileResponse(response) {
-  return Buffer.isBuffer(response) ? success(response) : failure("Incorrect file response format");
-}
 
 // src/qualtrics/index.ts
 async function execute(config) {
@@ -117,8 +114,9 @@ async function execute(config) {
     signal: controller.signal
   };
   if (body) {
-    if (typeof body === "string")
+    if (typeof body === "string") {
       headers.append("Content-Type", "application/json");
+    }
     options.method = "POST";
     options.headers = headers;
     options.body = body;
@@ -127,10 +125,19 @@ async function execute(config) {
   const response = await fetch(resource, options);
   clearTimeout(timer);
   if (response.ok) {
-    const data = await response.json();
-    return Promise.resolve(data);
+    const contentType = response.headers.get("content-type");
+    switch (contentType) {
+      case "application/json":
+        return Promise.resolve(await response.json());
+      case "application/csv":
+      case "application/tsv":
+      case "application/xml":
+        return Promise.resolve(await response.text());
+      default:
+        return Promise.resolve(response.body);
+    }
   } else {
-    const message = await response.text();
+    const message = await response.json();
     return Promise.reject(`${response.status}: ${message}`);
   }
 }
@@ -163,7 +170,7 @@ var getBearerToken = (connectionOptions) => async ({ clientId, clientSecret, sco
 
 // src/methods/getResponseExportProgress.ts
 var getResponseExportProgress = (connectionOptions) => async ({ exportProgressId, surveyId, bearerToken }) => {
-  const route = `/surveys/${surveyId}/export-responses/${exportProgressId}`;
+  const route = `/API/v3/surveys/${surveyId}/export-responses/${exportProgressId}`;
   try {
     const headers = getAuthHeaders(connectionOptions.apiToken, bearerToken);
     const config = {
@@ -183,7 +190,7 @@ var getResponseExportProgress = (connectionOptions) => async ({ exportProgressId
 
 // src/methods/getResponseExportFile.ts
 var getResponseExportFile = (connectionOptions) => async ({ surveyId, fileId, bearerToken }) => {
-  const route = `/surveys/${surveyId}/export-responses/${fileId}/file`;
+  const route = `/API/v3/surveys/${surveyId}/export-responses/${fileId}/file`;
   try {
     const headers = getAuthHeaders(connectionOptions.apiToken, bearerToken);
     const config = {
@@ -193,8 +200,7 @@ var getResponseExportFile = (connectionOptions) => async ({ surveyId, fileId, be
       timeout: connectionOptions.timeout
     };
     const response = await execute(config);
-    const result = safeParseFileResponse(response);
-    return result;
+    return response;
   } catch (error) {
     const message = getErrorMessage(error);
     return failure(message);
@@ -210,12 +216,14 @@ var startResponseExport = (connectionOptions) => async ({
   bearerToken = void 0,
   ...rest
 }) => {
-  const route = `/surveys/${surveyId}/export-responses`;
+  const route = `/API/v3/surveys/${surveyId}/export-responses`;
   try {
     const headers = getAuthHeaders(connectionOptions.apiToken, bearerToken);
     const body = JSON.stringify({
-      startDate: startDate.toISOString(),
-      endDate: endDate.toDateString(),
+      startDate: "2024-03-01T06:00:00Z",
+      //startDate.toISOString(),
+      endDate: "2024-03-05T06:00:00Z",
+      //endDate.toISOString(),
       format,
       ...rest
     });
@@ -259,6 +267,7 @@ var testConnection = (connectionOptions) => async (bearerToken) => {
 var createConnection = (options) => ({
   exportResponses: exportResponses(options),
   getBearerToken: getBearerToken(options),
+  getResponseExportFile: getResponseExportFile(options),
   getResponseExportProgress: getResponseExportProgress(options),
   startResponseExport: startResponseExport(options),
   testConnection: testConnection(options)

package/package.json

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

package/tests/utils.test.ts

@@ -5,7 +5,6 @@ import {
   safeParseTestResponse,
   safeParseStartFileExportResponse,
   safeParseFileProgressResponse,
-  safeParseFileResponse,
 } from '../src/utils/parsers'
 
 describe('safeParseBearerToken', () => {
@@ -126,7 +125,7 @@ describe('safeParseTestResponse', () => {
 
   it('should pass with correct data', () => {
     const res = fixture
-    const expected = success(undefined)
+    const expected = success('Connection successful')
     const parsed = safeParseTestResponse(res)
     expect(parsed).toStrictEqual(expected)
   })
@@ -140,21 +139,3 @@ 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)
-  })
-})