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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (8) hide show
  1. package/CHANGELOG.md +12 -0
  2. package/README.md +222 -29
  3. package/dist/index.d.mts +356 -1
  4. package/dist/index.d.ts +356 -1
  5. package/dist/index.js +539 -81
  6. package/dist/index.mjs +528 -81
  7. package/package.json +1 -1
  8. package/tests/utils.test.ts +360 -0
package/CHANGELOG.md CHANGED
@@ -1,5 +1,17 @@
1
1
  # @b-jones-rfd/qualtrics-api-tasks
2
2
 
3
+ ## 0.3.1
4
+
5
+ ### Patch Changes
6
+
7
+ - bb766b5: Cleaned up README
8
+
9
+ ## 0.3.0
10
+
11
+ ### Minor Changes
12
+
13
+ - 3bcc969: Added methods for Contacts and Distributions
14
+
3
15
  ## 0.2.0
4
16
 
5
17
  ### Minor Changes
package/README.md CHANGED
@@ -1,6 +1,9 @@
1
+ ![GitHub Actions CI](https://github.com/B-Jones-RFD/qualtrics-api-tasks/actions/workflows/main.yml/badge.svg)
2
+ [![npm version](https://img.shields.io/npm/v/@b-jones-rfd/qualtrics-api-tasks.svg?style=flat-square)](https://www.npmjs.com/package/@b-jones-rfd/qualtrics-api-tasks)
3
+ ![npm bundle size](https://img.shields.io/bundlephobia/min/%40b-jones-rfd%2Fqualtrics-api-tasks)
1
4
  [![code style: prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg?style=flat-square)](https://github.com/prettier/prettier)
2
5
 
3
- # qualtrics-api-tasks
6
+ # Qualtrics API Tasks
4
7
 
5
8
  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.
6
9
 
@@ -17,7 +20,7 @@ $ npm -v && node -v
17
20
  v20.11.1
18
21
  ```
19
22
 
20
- [PNPM] (https://pnpm.io/) is a awesome alternative to NPM and is recommended.
23
+ [PNPM](https://pnpm.io/) is a awesome alternative to NPM and is recommended.
21
24
 
22
25
  ## Table of contents
23
26
 
@@ -30,6 +33,13 @@ v20.11.1
30
33
  - [API](#api)
31
34
  - [createConnection](#createSiteConnection)
32
35
  - [Actions](#actions)
36
+ - [Authentication](#authentication)
37
+ - [Contacts](#contacts)
38
+ - [Distributions](#distributions)
39
+ - [Responses](#responses)
40
+ - [Mailing Lists](#mailing-lists)
41
+ - [Messages](#messages)
42
+ - [Utilities](#utilities)
33
43
  - [Responses](#responses)
34
44
  - [Contributing](#contributing)
35
45
  - [Versioning](#versioning)
@@ -79,12 +89,12 @@ const connectionOptions = {
79
89
  timeout: 20 * 1000, // optional timeout in milliseconds, default is 30 seconds
80
90
  }
81
91
 
82
- const connection: SiteConnection = createConnection(connectionOptions)
92
+ const connection: Connection = createConnection(connectionOptions)
83
93
 
84
94
  async function getBearerToken(clientId: string, clientSecret: string) {
85
- const contents = await connection.getBearerToken({ clientId, clientSecret })
86
- if (contents.success) return contents.data
87
- else throw new Error(contents.error)
95
+ const result = await connection.getBearerToken({ clientId, clientSecret })
96
+ if (result.success) return result.data
97
+ else throw new Error(result.error)
88
98
  }
89
99
  ```
90
100
 
@@ -95,20 +105,34 @@ Additionally, for single use or reduced import size, action factory methods can
95
105
  ```ts
96
106
  import { testConnection } from '@b-jones-rfd/qualtrics-api-tasks'
97
107
 
98
- async function testMyQualtricsConnection(listName: string) {
99
- const action = testConnection(connectionOpts)
100
- const contents = await action()
101
- if (contents.success) return 'Successful connection!'
102
- else throw new Error(contents.error)
108
+ async function testMyQualtricsConnection() {
109
+ const action = testConnection(connectionOptions)
110
+ const result = await action()
111
+ if (result.success) return result.data
112
+ else throw new Error(result.error)
103
113
  }
104
114
  ```
105
115
 
106
116
  ## API
107
117
 
108
- ### createSiteConnection
118
+ ### createConnection
119
+
120
+ Create a Qualtrics API Connection instance.
121
+
122
+ ```ts
123
+ type ConnectionFactory = (options: ConnectionOptions) => Connection
124
+ ```
109
125
 
110
126
  #### ConnectionOptions
111
127
 
128
+ ```ts
129
+ type ConnectionOptions = {
130
+ datacenterId: string
131
+ apiToken?: string
132
+ timeout?: number
133
+ }
134
+ ```
135
+
112
136
  `datacenterId`
113
137
 
114
138
  | Type | Description | Example | Required |
@@ -139,7 +163,155 @@ export type Action<TConfig, TResponse> = (
139
163
 
140
164
  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.
141
165
 
142
- #### exportResponses(options)
166
+ #### Authentication
167
+
168
+ ##### getBearerToken(options)
169
+
170
+ Implements [OAuth Authentication (Client Credentials)](https://api.qualtrics.com/9398592961ced-o-auth-authentication-client-credentials) and returns the access token as the result data.
171
+
172
+ `options`
173
+
174
+ | Property | Type | Description | Required |
175
+ | ------------ | ------ | --------------------------------- | -------- |
176
+ | clientId | string | Quatrics Client ID | Y |
177
+ | clientSecret | string | Qualtrics Client Password | Y |
178
+ | scope | string | Qualtrics Client requested scopes | Y |
179
+
180
+ #### Contacts
181
+
182
+ ##### getContactsImportStatus(options)
183
+
184
+ Implements [Get Contacts Import Status](https://api.qualtrics.com/c5d22705b1d45-get-transaction-contacts-import-status)
185
+
186
+ `options`
187
+
188
+ | Property | Type | Description | Required |
189
+ | ------------- | ------ | --------------------- | -------- |
190
+ | directoryId | string | Quatrics Directory ID | Y |
191
+ | importId | string | Contacts Import ID | Y |
192
+ | mailingListId | string | Mailing List ID | Y |
193
+ | bearerToken | string | Valid Bearer Token | N |
194
+
195
+ ##### getContactsImportSummary(options)
196
+
197
+ Implements [Get Contacts Import Summary](https://api.qualtrics.com/6f0480b307053-get-transaction-contacts-import-summary)
198
+
199
+ `options`
200
+
201
+ | Property | Type | Description | Required |
202
+ | ------------- | ------ | --------------------- | -------- |
203
+ | directoryId | string | Quatrics Directory ID | Y |
204
+ | importId | string | Contacts Import ID | Y |
205
+ | mailingListId | string | Mailing List ID | Y |
206
+ | bearerToken | string | Valid Bearer Token | N |
207
+
208
+ ##### importContacts(options)
209
+
210
+ Implements [Contact Import](https://api.qualtrics.com/1ac99fba8ca5b-contact-imports) multistep process
211
+
212
+ `options`
213
+
214
+ | Property | Type | Description | Required |
215
+ | --------------- | --------- | --------------------- | -------- |
216
+ | directoryId | string | Quatrics Directory ID | Y |
217
+ | mailingListId | string | Mailing List ID | Y |
218
+ | contacts | Contact[] | Contacts array | Y |
219
+ | transactionMeta | object | Transaction meta data | N |
220
+ | bearerToken | string | Valid Bearer Token | N |
221
+
222
+ ##### startContactsImport(options)
223
+
224
+ Implements [Create Transaction Contacts Import](https://api.qualtrics.com/bab13356ac724-create-transaction-contacts-import)
225
+
226
+ `options`
227
+
228
+ | Property | Type | Description | Required |
229
+ | --------------- | --------- | --------------------- | -------- |
230
+ | directoryId | string | Quatrics Directory ID | Y |
231
+ | mailingListId | string | Mailing List ID | Y |
232
+ | contacts | Contact[] | Contacts array | Y |
233
+ | transactionMeta | object | Transaction meta data | N |
234
+ | bearerToken | string | Valid Bearer Token | N |
235
+
236
+ #### Distributions
237
+
238
+ ##### createDistribution(options)
239
+
240
+ Implements [Create Distribution](https://api.qualtrics.com/573e3f0a94888-create-distribution).
241
+
242
+ `options`
243
+
244
+ | Property | Type | Description | Required | Default |
245
+ | ------------------ | ---------------------- | ---------------------------------- | -------- | ------- |
246
+ | libraryId | string | Quatrics Library ID | Y | |
247
+ | messageId | string | Qualtrics Message ID | Y | |
248
+ | messageText | string | Message text to send | N | |
249
+ | mailingListId | string | Mailing List ID | Y | |
250
+ | contactId | string | Contact lookup ID for individual | N | |
251
+ | transactionBatchId | string | Transaction Batch ID | N | |
252
+ | fromEmail | string | Originating email | Y | |
253
+ | replyToEmail | string | Email reply-to address | N | |
254
+ | fromName | string | Email from name | Y | |
255
+ | subject | string | Email subject | Y | |
256
+ | surveyId | string | Qualtrics Survey ID | Y | |
257
+ | expirationDate | Date | Distribution expiration date time | Y | |
258
+ | type | enum | Individual, Multiple, or Anonymous | Y | |
259
+ | embeddedData | Record<string, string> | Up to 10 subkeys | N | |
260
+ | sendDate | Date | Date time to send | Y | |
261
+ | bearerToken | string | Valid Bearer Token | N | |
262
+
263
+ ##### createReminder(options)
264
+
265
+ Implements [Create Reminder Distribution](https://api.qualtrics.com/764630bb0633a-create-reminder-distribution).
266
+
267
+ `options`
268
+
269
+ | Property | Type | Description | Required |
270
+ | -------------- | ---------------------- | ------------------------ | -------- |
271
+ | distributionId | string | Previous Distribution ID | Y |
272
+ | libraryId | string | Quatrics Library ID | Y |
273
+ | fromEmail | string | Originating email | Y |
274
+ | messageId | string | Qualtrics Message ID | Y |
275
+ | replyToEmail | string | Email reply-to address | N |
276
+ | fromName | string | Email from name | Y |
277
+ | subject | string | Email subject | Y |
278
+ | embeddedData | Record<string, string> | Up to 10 subkeys | N |
279
+ | sendDate | Date | Date time to send | Y |
280
+ | bearerToken | string | Valid Bearer Token | N |
281
+
282
+ ##### getDistribution(options)
283
+
284
+ Implements [Get Distribution](https://api.qualtrics.com/f5b1d8775d803-get-distribution)
285
+
286
+ `options`
287
+
288
+ | Property | Type | Description | Required |
289
+ | -------------- | ------ | ------------------ | -------- |
290
+ | distributionId | string | Distribution ID | Y |
291
+ | surveyId | string | Survey ID | Y |
292
+ | bearerToken | string | Valid Bearer Token | N |
293
+
294
+ ##### listDistributions(options)
295
+
296
+ Implements [List Distributions](https://api.qualtrics.com/234bb6b16cf6d-list-distributions)
297
+
298
+ `options`
299
+
300
+ | Property | Type | Description | Required | Default |
301
+ | ----------------------- | ------- | ------------------------------- | -------- | ------- |
302
+ | surveyId | string | Quatrics Survey ID | Y | |
303
+ | distributionRequestType | string | Distribution Request Type | Y | |
304
+ | mailingListId | string | Mailing List ID | Y | |
305
+ | sendStartDate | Date | Export start date and time | Y | |
306
+ | sendEndDate | Date | Export end date and time | Y | |
307
+ | skipToken | string | Pagination offset | N | |
308
+ | useNewPaginationScheme | boolean | Use updated pagination | N | false |
309
+ | pageSize | number | Distribution elements to return | N | 100 |
310
+ | bearerToken | string | Valid Bearer Token | N | |
311
+
312
+ #### Responses
313
+
314
+ ##### exportResponses(options)
143
315
 
144
316
  Implements [Survey Response File Export](https://api.qualtrics.com/u9e5lh4172v0v-survey-response-export-guide) multistep process.
145
317
 
@@ -172,19 +344,7 @@ Implements [Survey Response File Export](https://api.qualtrics.com/u9e5lh4172v0v
172
344
  | sortByLastModifiedDate | boolean | Sort responses by modified date | N | false |
173
345
  | bearerToken | string | Valid Bearer Token | N | |
174
346
 
175
- #### getBearerToken(options)
176
-
177
- Implements [OAuth Authentication (Client Credentials)](https://api.qualtrics.com/9398592961ced-o-auth-authentication-client-credentials)
178
-
179
- `options`
180
-
181
- | Property | Type | Description | Required |
182
- | ------------ | ------ | --------------------------------- | -------- |
183
- | clientId | string | Quatrics Client ID | Y |
184
- | clientSecret | string | Qualtrics Client Password | Y |
185
- | scope | string | Qualtrics Client requested scopes | Y |
186
-
187
- #### getResponseExportFile(options)
347
+ ##### getResponseExportFile(options)
188
348
 
189
349
  Implements [Get Response Export File](https://api.qualtrics.com/41296b6f2e828-get-response-export-file)
190
350
 
@@ -196,7 +356,7 @@ Implements [Get Response Export File](https://api.qualtrics.com/41296b6f2e828-ge
196
356
  | fileId | string | File ID | Y |
197
357
  | bearerToken | string | Valid Bearer Token | N |
198
358
 
199
- #### getResponseExportProgress(options)
359
+ ##### getResponseExportProgress(options)
200
360
 
201
361
  Implements [Get Response Export Progress](https://api.qualtrics.com/37e6a66f74ab4-get-response-export-progress)
202
362
 
@@ -208,7 +368,38 @@ Implements [Get Response Export Progress](https://api.qualtrics.com/37e6a66f74ab
208
368
  | exportProgressId | string | Progress ID | Y |
209
369
  | bearerToken | string | Valid Bearer Token | N |
210
370
 
211
- #### startResponseExports(options)
371
+ #### Mailing Lists
372
+
373
+ ##### createMailingList(options)
374
+
375
+ Implements [Create Mailing List](https://api.qualtrics.com/3f633e4cea6cd-create-mailing-list)
376
+
377
+ `options`
378
+
379
+ | Property | Type | Description | Required | Default |
380
+ | ---------------------- | ------- | -------------------------------- | -------- | ------- |
381
+ | directoryId | string | Quatrics Directory ID | Y | |
382
+ | name | string | Mailing List Name | Y | |
383
+ | ownerId | string | Owner ID | Y | |
384
+ | prioritizeListMetadata | boolean | Import metadata as list metadata | N | false |
385
+ | bearerToken | string | Valid Bearer Token | N | |
386
+
387
+ #### Messages
388
+
389
+ ##### listLibraryMessages(options)
390
+
391
+ Implements [List Library Messages](https://api.qualtrics.com/1d60a66b340fa-list-library-messages)
392
+
393
+ `options`
394
+
395
+ | Property | Type | Description | Required |
396
+ | ----------- | ------ | ------------------- | -------- |
397
+ | libraryId | string | Quatrics Library ID | Y |
398
+ | category | string | Message category | N |
399
+ | offset | number | Pagination offset | N |
400
+ | bearerToken | string | Valid Bearer Token | N |
401
+
402
+ ##### startResponseExports(options)
212
403
 
213
404
  Implements [Start Response Exports](https://api.qualtrics.com/6b00592b9c013-start-response-export)
214
405
 
@@ -241,7 +432,9 @@ Implements [Start Response Exports](https://api.qualtrics.com/6b00592b9c013-star
241
432
  | sortByLastModifiedDate | boolean | Sort responses by modified date | N | false |
242
433
  | bearerToken | string | Valid Bearer Token | N | |
243
434
 
244
- #### testConnection(bearerToken)
435
+ #### Utilities
436
+
437
+ ##### testConnection(bearerToken)
245
438
 
246
439
  | Parameter | Type | Description | Required |
247
440
  | ----------- | ------ | ------------------ | -------- |