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

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @b-jones-rfd/qualtrics-api-tasks
 
+## 0.1.0
+
+### Minor Changes
+
+- efa27c7: Implemented survey file response methods
+
+## 0.0.5
+
+### Patch Changes
+
+- df0e350: Implemented testConnection and getBearerToken methods
+
 ## 0.0.4
 
 ### Patch Changes

package/README.md

@@ -1,2 +1,288 @@
+[![code style: prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg?style=flat-square)](https://github.com/prettier/prettier)
+
 # qualtrics-api-tasks
-Helpers to perform common tasks using the Qualtrics API
+
+Helpers to perform common tasks using the [Qualtrics API](https://api.qualtrics.com/). This is an exercise to avoid code reuse in my own projects. Use at your own risk.
+
+## Prerequisites
+
+This project requires NodeJS (version >= 18) and NPM.
+[Node](http://nodejs.org/) and [NPM](https://npmjs.org/) are really easy to install.
+To make sure you have them available on your machine,
+try running the following command.
+
+```sh
+$ npm -v && node -v
+10.2.4
+v20.11.1
+```
+
+[PNPM] (https://pnpm.io/) is a awesome alternative to NPM and is recommended.
+
+## Table of contents
+
+- [Qualtrics API Tasks](#qualtics-api-tasks)
+  - [Prerequisites](#prerequisites)
+  - [Table of contents](#table-of-contents)
+  - [Getting Started](#getting-started)
+  - [Installation](#installation)
+  - [Usage](#usage)
+  - [API](#api)
+    - [createConnection](#createSiteConnection)
+    - [Actions](#actions)
+    - [Responses](#responses)
+  - [Contributing](#contributing)
+  - [Versioning](#versioning)
+  - [Authors](#authors)
+  - [License](#license)
+
+## Getting Started
+
+These instructions will get you a copy of the project up and running on your local machine for development and testing purposes. See deployment for notes on how to deploy the project on a live system.
+
+## Installation
+
+**BEFORE YOU INSTALL:** please read the [prerequisites](#prerequisites)
+
+To install and set up the library, run:
+
+```sh
+$ npm i @b-jones-rfd/qualtrics-api-tasks
+```
+
+Or if you prefer using Yarn:
+
+```sh
+$ yarn add @b-jones-rfd/qualtrics-api-tasks
+```
+
+Or for PNPM:
+
+```sh
+$ pnpm add @b-jones-rfd/qualtrics-api-tasks
+```
+
+## Usage
+
+### Instance Methods
+
+Actions can be performed against the Qualtrics API using instance methods on a Qualtrics Connection instance.
+
+If authenticating using [OAuth 2.0](https://api.qualtrics.com/9398592961ced-o-auth-authentication-client-credentials) use the getBearerToken action with a Client ID and secret to obtain a bearer token. If authenticating with an [API Token](https://api.qualtrics.com/2b4ffbd8af74e-api-key-authentication) pass the token as a connection option using the apiToken property.
+
+```ts
+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
+}
+
+const connection: SiteConnection = createConnection(connectionOptions)
+
+async function getBearerToken(clientId: string, clientSecret: string) {
+  const contents = await connection.getBearerToken({ clientId, clientSecret })
+  if (contents.success) return contents.data
+  else throw new Error(contents.error)
+}
+```
+
+### Factory Action Methods
+
+Additionally, for single use or reduced import size, action factory methods can be imported directly. Call the factory method with a SiteConnectionOptions object to return an asynchronous action function that can be called directly.
+
+```ts
+import { testConnection } from '@b-jones-rfd/qualtrics-api-tasks'
+
+async function testMyQualtricsConnection(listName: string) {
+  const action = testConnection(connectionOpts)
+  const contents = await action()
+  if (contents.success) return 'Successful connection!'
+  else throw new Error(contents.error)
+}
+```
+
+## API
+
+### createSiteConnection
+
+#### ConnectionOptions
+
+`datacenterId`
+
+| Type   | Description              | Example | Required |
+| ------ | ------------------------ | ------- | -------- |
+| string | Qualtrics Data Center Id | 'ca1'   | Y        |
+
+`apiToken`
+
+| Type   | Description         | Required |
+| ------ | ------------------- | -------- |
+| string | Qualtrics API Token | N        |
+
+`timeout`
+
+| Type   | Default value | Description               | Example               | Required |
+| ------ | ------------- | ------------------------- | --------------------- | -------- |
+| number | 30000         | Qualtrics request timeout | sharepoint.domain.com | N        |
+
+### Actions
+
+Connection instance action methods.
+
+```ts
+export type Action<TConfig, TResponse> = (
+  options: TConfig
+) => Promise<Result<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.
+
+#### 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        |
+| scope        | string | Qualtrics Client requested scopes | Y        |
+
+#### getResponseExportFile(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
+
+Responses are provided based on the Result type. Success can be determined by checking the success property.
+
+```ts
+export type Result<TResponse> = Success<TResponse> | Failure
+```
+
+### Success
+
+Response is returned in the data property.
+
+```ts
+type Success<TResponse> = { success: true; data: TResponse }
+```
+
+### Failure
+
+Errors are returned in the error property.
+
+```ts
+type Failure = { success: false; error: string }
+```
+
+## Contributing
+
+This is a pet project to save me time at work. It is still under development and you should use at your own risk.
+
+## Versioning
+
+We use [SemVer](http://semver.org/) for versioning. For the versions available, see the [tags on this repository](https://github.com/B-Jones-RFD/qualtrics-api-tasks/tags).
+
+## Authors
+
+- **B Jones RFD** - _Package Noob_ - [B-Jones-RFD](https://github.com/B-Jones-RFD)
+
+## License
+
+[MIT License](https://github.com/B-Jones-RFD/qualtrics-api-tasks/blob/main/LICENSE)

package/dist/index.d.mts

@@ -1,3 +1,103 @@
-declare const hello: () => void;
+type Success<T> = {
+    success: true;
+    data: T;
+};
+type Failure = {
+    success: false;
+    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;
+    apiToken?: string;
+    timeout?: number;
+};
+type ActionFactory<TParams, TResponse> = (options: ConnectionOptions) => Action<TParams, TResponse>;
+type Connection = {
+    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;
+};
 
-export { hello };
+declare const createConnection: ConnectionFactory;
+
+declare const exportResponses: ActionFactory<ExportResponsesOptions, Buffer>;
+
+declare const getBearerToken: ActionFactory<{
+    clientId: string;
+    clientSecret: string;
+    scope: string;
+}, string>;
+
+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 ExportResponsesOptions, type Failure, type FileProgressResponse, type ResponseFormat, type Result, type Success, createConnection, exportResponses, getBearerToken, getResponseExportFile, getResponseExportProgress, startResponseExport, testConnection };

package/dist/index.d.ts

@@ -1,3 +1,103 @@
-declare const hello: () => void;
+type Success<T> = {
+    success: true;
+    data: T;
+};
+type Failure = {
+    success: false;
+    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;
+    apiToken?: string;
+    timeout?: number;
+};
+type ActionFactory<TParams, TResponse> = (options: ConnectionOptions) => Action<TParams, TResponse>;
+type Connection = {
+    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;
+};
 
-export { hello };
+declare const createConnection: ConnectionFactory;
+
+declare const exportResponses: ActionFactory<ExportResponsesOptions, Buffer>;
+
+declare const getBearerToken: ActionFactory<{
+    clientId: string;
+    clientSecret: string;
+    scope: string;
+}, string>;
+
+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 ExportResponsesOptions, type Failure, type FileProgressResponse, type ResponseFormat, type Result, type Success, createConnection, exportResponses, getBearerToken, getResponseExportFile, getResponseExportProgress, startResponseExport, testConnection };

package/dist/index.js

@@ -20,13 +20,288 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var src_exports = {};
 __export(src_exports, {
-  hello: () => hello
+  createConnection: () => createConnection,
+  exportResponses: () => exportResponses,
+  getBearerToken: () => getBearerToken,
+  getResponseExportFile: () => getResponseExportFile,
+  getResponseExportProgress: () => getResponseExportProgress,
+  startResponseExport: () => startResponseExport,
+  testConnection: () => testConnection
 });
 module.exports = __toCommonJS(src_exports);
-var hello = () => {
-  console.log("Nothing to see here!");
+
+// src/utils/index.ts
+function success(data) {
+  return {
+    success: true,
+    data
+  };
+}
+function failure(error) {
+  return {
+    success: false,
+    error
+  };
+}
+function getErrorMessage(error) {
+  return error ? typeof error === "object" && "message" in error && typeof error.message === "string" ? error.message : error.toString() : "An error occured";
+}
+function getAuthHeaders(apiToken, bearerToken) {
+  if (apiToken)
+    return new Headers({
+      "X-API-TOKEN": apiToken
+    });
+  if (bearerToken) {
+    return new Headers({
+      Authorization: `Bearer ${bearerToken}`
+    });
+  }
+  throw new Error(
+    "Unable to authorize request. Bearer Token or Api Token required."
+  );
+}
+
+// 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;
+  const host = `https://${datacenterId}.qualtrics.com`;
+  const resource = new URL(route, host);
+  const controller = new AbortController();
+  const options = {
+    method: "GET",
+    headers,
+    signal: controller.signal
+  };
+  if (body) {
+    if (typeof body === "string")
+      headers.append("Content-Type", "application/json");
+    options.method = "POST";
+    options.headers = headers;
+    options.body = body;
+  }
+  const timer = setTimeout(() => controller.abort(), timeout ?? 30 * 1e3);
+  const response = await fetch(resource, options);
+  clearTimeout(timer);
+  if (response.ok) {
+    const data = await response.json();
+    return Promise.resolve(data);
+  } else {
+    const message = await response.text();
+    return Promise.reject(`${response.status}: ${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/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";
+  try {
+    const headers = getAuthHeaders(connectionOptions.apiToken, bearerToken);
+    const config = {
+      datacenterId: connectionOptions.datacenterId,
+      route,
+      headers,
+      timeout: connectionOptions.timeout
+    };
+    const response = await execute(config);
+    const result = safeParseTestResponse(response);
+    return result;
+  } catch (error) {
+    const message = getErrorMessage(error);
+    return failure(message);
+  }
+};
+
+// src/createConnection.ts
+var createConnection = (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 = {
-  hello
+  createConnection,
+  exportResponses,
+  getBearerToken,
+  getResponseExportFile,
+  getResponseExportProgress,
+  startResponseExport,
+  testConnection
 });

package/dist/index.mjs

@@ -1,7 +1,274 @@
-// src/index.ts
-var hello = () => {
-  console.log("Nothing to see here!");
+// src/utils/index.ts
+function success(data) {
+  return {
+    success: true,
+    data
+  };
+}
+function failure(error) {
+  return {
+    success: false,
+    error
+  };
+}
+function getErrorMessage(error) {
+  return error ? typeof error === "object" && "message" in error && typeof error.message === "string" ? error.message : error.toString() : "An error occured";
+}
+function getAuthHeaders(apiToken, bearerToken) {
+  if (apiToken)
+    return new Headers({
+      "X-API-TOKEN": apiToken
+    });
+  if (bearerToken) {
+    return new Headers({
+      Authorization: `Bearer ${bearerToken}`
+    });
+  }
+  throw new Error(
+    "Unable to authorize request. Bearer Token or Api Token required."
+  );
+}
+
+// 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;
+  const host = `https://${datacenterId}.qualtrics.com`;
+  const resource = new URL(route, host);
+  const controller = new AbortController();
+  const options = {
+    method: "GET",
+    headers,
+    signal: controller.signal
+  };
+  if (body) {
+    if (typeof body === "string")
+      headers.append("Content-Type", "application/json");
+    options.method = "POST";
+    options.headers = headers;
+    options.body = body;
+  }
+  const timer = setTimeout(() => controller.abort(), timeout ?? 30 * 1e3);
+  const response = await fetch(resource, options);
+  clearTimeout(timer);
+  if (response.ok) {
+    const data = await response.json();
+    return Promise.resolve(data);
+  } else {
+    const message = await response.text();
+    return Promise.reject(`${response.status}: ${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/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";
+  try {
+    const headers = getAuthHeaders(connectionOptions.apiToken, bearerToken);
+    const config = {
+      datacenterId: connectionOptions.datacenterId,
+      route,
+      headers,
+      timeout: connectionOptions.timeout
+    };
+    const response = await execute(config);
+    const result = safeParseTestResponse(response);
+    return result;
+  } catch (error) {
+    const message = getErrorMessage(error);
+    return failure(message);
+  }
+};
+
+// src/createConnection.ts
+var createConnection = (options) => ({
+  exportResponses: exportResponses(options),
+  getBearerToken: getBearerToken(options),
+  getResponseExportProgress: getResponseExportProgress(options),
+  startResponseExport: startResponseExport(options),
+  testConnection: testConnection(options)
+});
 export {
-  hello
+  createConnection,
+  exportResponses,
+  getBearerToken,
+  getResponseExportFile,
+  getResponseExportProgress,
+  startResponseExport,
+  testConnection
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@b-jones-rfd/qualtrics-api-tasks",
-  "version": "0.0.4",
+  "version": "0.1.0",
   "description": "Perform common tasks using the Qualtrics API",
   "private": false,
   "main": "./dist/index.js",
@@ -11,6 +11,8 @@
   "license": "MIT",
   "devDependencies": {
     "@changesets/cli": "^2.27.1",
+    "@types/node": "^20.11.20",
+    "prettier": "^3.2.5",
     "tsup": "^8.0.2",
     "typescript": "^5.3.3",
     "vitest": "^1.3.1"

package/tests/utils.test.ts

@@ -0,0 +1,160 @@
+import { describe, it, expect } from 'vitest'
+import { success, failure } from '../src/utils'
+import {
+  safeParseBearerToken,
+  safeParseTestResponse,
+  safeParseStartFileExportResponse,
+  safeParseFileProgressResponse,
+  safeParseFileResponse,
+} from '../src/utils/parsers'
+
+describe('safeParseBearerToken', () => {
+  const fixture = {
+    access_token: 'sometoken',
+    token_type: 'Bearer',
+  }
+
+  it('should pass with correct data', () => {
+    const res = fixture
+    const expected = success(fixture.access_token)
+    const parsed = safeParseBearerToken(res)
+    expect(parsed).toStrictEqual(expected)
+  })
+
+  it('should fail when token is incorrect type', () => {
+    const res = {
+      result: 'bad result',
+    }
+    const expected = failure('Incorrect token format')
+    const parsed = safeParseBearerToken(res)
+    expect(parsed).toStrictEqual(expected)
+  })
+})
+
+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: {
+      userId: 'testUser',
+    },
+  }
+
+  it('should pass with correct data', () => {
+    const res = fixture
+    const expected = success(undefined)
+    const parsed = safeParseTestResponse(res)
+    expect(parsed).toStrictEqual(expected)
+  })
+
+  it('should fail when response is incorrect type', () => {
+    const res = {
+      result: 'bad result',
+    }
+    const expected = failure('Incorrect test response format')
+    const parsed = safeParseTestResponse(res)
+    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)
+  })
+})