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

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @b-jones-rfd/qualtrics-api-tasks
 
+## 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`);
@@ -149,8 +149,10 @@ async function execute(config) {
     signal: controller.signal
   };
   if (body) {
-    if (typeof body === "string")
+    if (typeof body === "string") {
       headers.append("Content-Type", "application/json");
+      headers.append("Accept", "application/json");
+    }
     options.method = "POST";
     options.headers = headers;
     options.body = body;
@@ -162,7 +164,7 @@ async function execute(config) {
     const data = await response.json();
     return Promise.resolve(data);
   } else {
-    const message = await response.text();
+    const message = await response.json();
     return Promise.reject(`${response.status}: ${message}`);
   }
 }
@@ -246,8 +248,10 @@ var startResponseExport = (connectionOptions) => async ({
   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 +295,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`);
@@ -117,8 +117,10 @@ async function execute(config) {
     signal: controller.signal
   };
   if (body) {
-    if (typeof body === "string")
+    if (typeof body === "string") {
       headers.append("Content-Type", "application/json");
+      headers.append("Accept", "application/json");
+    }
     options.method = "POST";
     options.headers = headers;
     options.body = body;
@@ -130,7 +132,7 @@ async function execute(config) {
     const data = await response.json();
     return Promise.resolve(data);
   } else {
-    const message = await response.text();
+    const message = await response.json();
     return Promise.reject(`${response.status}: ${message}`);
   }
 }
@@ -214,8 +216,10 @@ var startResponseExport = (connectionOptions) => async ({
   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 +263,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.1.1",
   "description": "Perform common tasks using the Qualtrics API",
   "private": false,
   "main": "./dist/index.js",

package/tests/utils.test.ts

@@ -126,7 +126,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)
   })