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

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @b-jones-rfd/qualtrics-api-tasks
 
+## 0.0.5
+
+### Patch Changes
+
+- df0e350: Implemented testConnection and getBearerToken methods
+
 ## 0.0.4
 
 ### Patch Changes

package/README.md

@@ -1,2 +1,199 @@
+[![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.
+
+#### getBearerToken()
+
+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        |
+
+#### testConnection(options)
+
+`options`
+
+| Property    | 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/sp-rest-connect/blob/main/LICENSE)

package/dist/index.d.mts

@@ -1,3 +1,35 @@
-declare const hello: () => void;
+type Success<T> = {
+    success: true;
+    data: T;
+};
+type Failure = {
+    success: false;
+    error: string;
+};
+type Result<T> = Success<T> | Failure;
+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 = {
+    testConnection: Action<string | undefined, void>;
+    getBearerToken: Action<{
+        clientId: string;
+        clientSecret: string;
+    }, string>;
+};
+type ConnectionFactory = (options: ConnectionOptions) => Connection;
 
-export { hello };
+declare const createConnection: ConnectionFactory;
+
+declare const getBearerToken: ActionFactory<{
+    clientId: string;
+    clientSecret: string;
+}, string>;
+
+declare const testConnection: ActionFactory<string | undefined, void>;
+
+export { type Action, type ActionFactory, type Connection, type ConnectionFactory, type ConnectionOptions, type Failure, type Result, type Success, createConnection, getBearerToken, testConnection };

package/dist/index.d.ts

@@ -1,3 +1,35 @@
-declare const hello: () => void;
+type Success<T> = {
+    success: true;
+    data: T;
+};
+type Failure = {
+    success: false;
+    error: string;
+};
+type Result<T> = Success<T> | Failure;
+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 = {
+    testConnection: Action<string | undefined, void>;
+    getBearerToken: Action<{
+        clientId: string;
+        clientSecret: string;
+    }, string>;
+};
+type ConnectionFactory = (options: ConnectionOptions) => Connection;
 
-export { hello };
+declare const createConnection: ConnectionFactory;
+
+declare const getBearerToken: ActionFactory<{
+    clientId: string;
+    clientSecret: string;
+}, string>;
+
+declare const testConnection: ActionFactory<string | undefined, void>;
+
+export { type Action, type ActionFactory, type Connection, type ConnectionFactory, type ConnectionOptions, type Failure, type Result, type Success, createConnection, getBearerToken, testConnection };

package/dist/index.js

@@ -20,13 +20,133 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var src_exports = {};
 __export(src_exports, {
-  hello: () => hello
+  createConnection: () => createConnection,
+  getBearerToken: () => getBearerToken,
+  testConnection: () => testConnection
 });
 module.exports = __toCommonJS(src_exports);
-var hello = () => {
-  console.log("Nothing to see here!");
+
+// src/utils.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 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({
+      "X-API-TOKEN": apiToken
+    });
+  if (bearerToken) {
+    return new Headers({
+      Authorization: bearerToken
+    });
+  }
+  throw new Error(
+    "Unable to authorize request. Bearer Token or Api Token required."
+  );
+}
+
+// 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 }) => {
+  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", "manage:all");
+    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/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) => ({
+  testConnection: testConnection(options),
+  getBearerToken: getBearerToken(options)
+});
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  hello
+  createConnection,
+  getBearerToken,
+  testConnection
 });

package/dist/index.mjs

@@ -1,7 +1,123 @@
-// src/index.ts
-var hello = () => {
-  console.log("Nothing to see here!");
+// src/utils.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 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({
+      "X-API-TOKEN": apiToken
+    });
+  if (bearerToken) {
+    return new Headers({
+      Authorization: bearerToken
+    });
+  }
+  throw new Error(
+    "Unable to authorize request. Bearer Token or Api Token required."
+  );
+}
+
+// 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 }) => {
+  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", "manage:all");
+    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/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) => ({
+  testConnection: testConnection(options),
+  getBearerToken: getBearerToken(options)
+});
 export {
-  hello
+  createConnection,
+  getBearerToken,
+  testConnection
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@b-jones-rfd/qualtrics-api-tasks",
-  "version": "0.0.4",
+  "version": "0.0.5",
   "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,54 @@
+import { describe, it, expect } from 'vitest'
+import {
+  success,
+  failure,
+  safeParseBearerToken,
+  safeParseTestResponse,
+} from '../src/utils'
+
+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('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)
+  })
+})