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

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @b-jones-rfd/qualtrics-api-tasks
 
+## 0.3.0
+
+### Minor Changes
+
+- 3bcc969: Added methods for Contacts and Distributions
+
 ## 0.2.0
 
 ### Minor Changes

package/README.md

@@ -139,6 +139,64 @@ export type Action<TConfig, 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.
 
+#### createDistribution(options)
+
+Implements [Create Distribution](https://api.qualtrics.com/573e3f0a94888-create-distribution).
+
+`options`
+
+| Property           | Type                   | Description                        | Required | Default |
+| ------------------ | ---------------------- | ---------------------------------- | -------- | ------- |
+| libraryId          | string                 | Quatrics Library ID                | Y        |         |
+| messageId          | string                 | Qualtrics Message ID               | Y        |         |
+| messageText        | string                 | Message text to send               | N        |         |
+| mailingListId      | string                 | Mailing List ID                    | Y        |         |
+| contactId          | string                 | Contact lookup ID for individual   | N        |         |
+| transactionBatchId | string                 | Transaction Batch ID               | N        |         |
+| fromEmail          | string                 | Originating email                  | Y        |         |
+| replyToEmail       | string                 | Email reply-to address             | N        |         |
+| fromName           | string                 | Email from name                    | Y        |         |
+| subject            | string                 | Email subject                      | Y        |         |
+| surveyId           | string                 | Qualtrics Survey ID                | Y        |         |
+| expirationDate     | Date                   | Distribution expiration date time  | Y        |         |
+| type               | enum                   | Individual, Multiple, or Anonymous | Y        |         |
+| embeddedData       | Record<string, string> | Up to 10 subkeys                   | N        |         |
+| sendDate           | Date                   | Date time to send                  | Y        |         |
+| bearerToken        | string                 | Valid Bearer Token                 | N        |         |
+
+#### createMailingList(options)
+
+Implements [Create Mailing List](https://api.qualtrics.com/3f633e4cea6cd-create-mailing-list)
+
+`options`
+
+| Property               | Type    | Description                      | Required | Default |
+| ---------------------- | ------- | -------------------------------- | -------- | ------- |
+| directoryId            | string  | Quatrics Directory ID            | Y        |         |
+| name                   | string  | Mailing List Name                | Y        |         |
+| ownerId                | string  | Owner ID                         | Y        |         |
+| prioritizeListMetadata | boolean | Import metadata as list metadata | N        | false   |
+| bearerToken            | string  | Valid Bearer Token               | N        |         |
+
+#### createReminder(options)
+
+Implements [Create Reminder Distribution](https://api.qualtrics.com/764630bb0633a-create-reminder-distribution).
+
+`options`
+
+| Property       | Type                   | Description              | Required | Default |
+| -------------- | ---------------------- | ------------------------ | -------- | ------- |
+| distributionId | string                 | Previous Distribution ID | Y        |         |
+| libraryId      | string                 | Quatrics Library ID      | Y        |         |
+| messageId      | string                 | Qualtrics Message ID     | Y        |         |
+| fromEmail      | string                 | Originating email        | Y        |         |
+| replyToEmail   | string                 | Email reply-to address   | N        |         |
+| fromName       | string                 | Email from name          | Y        |         |
+| subject        | string                 | Email subject            | Y        |         |
+| embeddedData   | Record<string, string> | Up to 10 subkeys         | N        |         |
+| sendDate       | Date                   | Date time to send        | Y        |         |
+| bearerToken    | string                 | Valid Bearer Token       | N        |         |
+
 #### exportResponses(options)
 
 Implements [Survey Response File Export](https://api.qualtrics.com/u9e5lh4172v0v-survey-response-export-guide) multistep process.
@@ -184,6 +242,44 @@ Implements [OAuth Authentication (Client Credentials)](https://api.qualtrics.com
 | clientSecret | string | Qualtrics Client Password         | Y        |
 | scope        | string | Qualtrics Client requested scopes | Y        |
 
+#### getContactsImportStatus(options)
+
+Implements [Get Contacts Import Status](https://api.qualtrics.com/c5d22705b1d45-get-transaction-contacts-import-status)
+
+`options`
+
+| Property      | Type   | Description           | Required |
+| ------------- | ------ | --------------------- | -------- |
+| directoryId   | string | Quatrics Directory ID | Y        |
+| importId      | string | Contacts Import ID    | Y        |
+| mailingListId | string | Mailing List ID       | Y        |
+| bearerToken   | string | Valid Bearer Token    | N        |
+
+#### getContactsImportSummary(options)
+
+Implements [Get Contacts Import Summary](https://api.qualtrics.com/6f0480b307053-get-transaction-contacts-import-summary)
+
+`options`
+
+| Property      | Type   | Description           | Required |
+| ------------- | ------ | --------------------- | -------- |
+| directoryId   | string | Quatrics Directory ID | Y        |
+| importId      | string | Contacts Import ID    | Y        |
+| mailingListId | string | Mailing List ID       | Y        |
+| bearerToken   | string | Valid Bearer Token    | N        |
+
+#### getDistribution(options)
+
+Implements [Get Distribution](https://api.qualtrics.com/f5b1d8775d803-get-distribution)
+
+`options`
+
+| Property       | Type   | Description        | Required |
+| -------------- | ------ | ------------------ | -------- |
+| distributionId | string | Distribution ID    | Y        |
+| surveyId       | string | Survey ID          | Y        |
+| bearerToken    | string | Valid Bearer Token | N        |
+
 #### getResponseExportFile(options)
 
 Implements [Get Response Export File](https://api.qualtrics.com/41296b6f2e828-get-response-export-file)
@@ -208,6 +304,65 @@ Implements [Get Response Export Progress](https://api.qualtrics.com/37e6a66f74ab
 | exportProgressId | string | Progress ID        | Y        |
 | bearerToken      | string | Valid Bearer Token | N        |
 
+#### importContacts(options)
+
+Implements [Contact Import](https://api.qualtrics.com/1ac99fba8ca5b-contact-imports) multistep process
+
+`options`
+
+| Property        | Type      | Description           | Required |
+| --------------- | --------- | --------------------- | -------- |
+| directoryId     | string    | Quatrics Directory ID | Y        |
+| mailingListId   | string    | Mailing List ID       | Y        |
+| contacts        | Contact[] | Contacts array        | Y        |
+| transactionMeta | object    | Transaction meta data | N        |
+| bearerToken     | string    | Valid Bearer Token    | N        |
+
+#### listDistributions(options)
+
+Implements [List Distributions](https://api.qualtrics.com/234bb6b16cf6d-list-distributions)
+
+`options`
+
+| Property                | Type    | Description                     | Required | Default |
+| ----------------------- | ------- | ------------------------------- | -------- | ------- |
+| surveyId                | string  | Quatrics Survey ID              | Y        |         |
+| distributionRequestType | string  | Distribution Request Type       | Y        |         |
+| mailingListId           | string  | Mailing List ID                 | Y        |         |
+| sendStartDate           | Date    | Export start date and time      | Y        |         |
+| sendEndDate             | Date    | Export end date and time        | Y        |         |
+| skipToken               | string  | Pagination offset               | N        |         |
+| useNewPaginationScheme  | boolean | Use updated pagination          | N        | false   |
+| pageSize                | number  | Distribution elements to return | N        | 100     |
+| bearerToken             | string  | Valid Bearer Token              | N        |         |
+
+#### listLibraryMessages(options)
+
+Implements [List Library Messages](https://api.qualtrics.com/1d60a66b340fa-list-library-messages)
+
+`options`
+
+| Property    | Type   | Description         | Required |
+| ----------- | ------ | ------------------- | -------- |
+| libraryId   | string | Quatrics Library ID | Y        |
+| category    | string | Message category    | N        |
+| offset      | number | Pagination offset   | N        |
+| bearerToken | string | Valid Bearer Token  | N        |
+
+#### startContactsImport(options)
+
+Implements [Create Transaction Contacts Import](https://api.qualtrics.com/bab13356ac724-create-transaction-contacts-import)
+
+`options`
+
+| Property        | Type      | Description           | Required |
+| --------------- | --------- | --------------------- | -------- |
+| directoryId     | string    | Quatrics Directory ID | Y        |
+| mailingListId   | string    | Mailing List ID       | Y        |
+| contacts        | Contact[] | Contacts array        | Y        |
+| transactionMeta | object    | Transaction meta data | N        |
+| bearerToken     | string    | Valid Bearer Token    | N        |
+
 #### startResponseExports(options)
 
 Implements [Start Response Exports](https://api.qualtrics.com/6b00592b9c013-start-response-export)

package/dist/index.d.mts

@@ -8,6 +8,63 @@ type Failure = {
 };
 type Result<T> = Success<T> | Failure;
 type ResponseFormat = 'csv' | 'json' | 'ndjson' | 'spss' | 'tsv' | 'xml';
+type DistributionRequestType = 'Invite' | 'ThankYou' | 'Reminder' | 'Email' | 'Portal' | 'PortalInvite' | 'GeneratedInvite';
+type Contact = {
+    firstName?: string;
+    lastName?: string;
+    email: string;
+    extRef?: string;
+    embeddedData?: Record<string, string>;
+    language?: string;
+    unsubscribed?: boolean;
+    transactionData?: object;
+};
+type Distribution = {
+    id: string;
+    parentDistributionId: string;
+    ownerId: string;
+    organizationId: string;
+    requestStatus: string;
+    requestType: DistributionRequestType;
+    sendDate: string;
+    createdDate: string;
+    modifiedDate: string;
+    headers: {
+        fromEmail: string;
+        replyToEmail: string;
+        fromName: string;
+        subject: string;
+    };
+    recipients: {
+        mailingListId: string;
+        contactId: string;
+        libraryId: string;
+        sampleId: string;
+    };
+    message: {
+        libraryId: string;
+        messageId: string;
+        messageText: string;
+        messageType: string;
+    };
+    surveyLink: {
+        surveyId: string;
+        expirationDate: string;
+        linkType: 'Individual' | 'Multiple' | 'Anonymous';
+    };
+    stats: {
+        sent: number;
+        failed: number;
+        started: number;
+        bounced: number;
+        opened: number;
+        skipped: number;
+        finished: number;
+        complaints: number;
+        blocked: number;
+    };
+    embeddedData: Record<string, string>;
+};
 type Action<TConfig, TResponse> = (options: TConfig) => Promise<Result<TResponse>>;
 type ConnectionOptions = {
     datacenterId: string;
@@ -16,12 +73,39 @@ type ConnectionOptions = {
 };
 type ActionFactory<TParams, TResponse> = (options: ConnectionOptions) => Action<TParams, TResponse>;
 type Connection = {
+    createDistribution: Action<CreateDistributionOptions, string>;
+    createMailingList: Action<{
+        directoryId: string;
+        name: string;
+        ownerId: string;
+        prioritizeListMetadata?: boolean;
+        bearerToken?: string;
+    }, string>;
+    createReminder: Action<CreateReminderOptions, string>;
+    distributeSurveys: Action<DistributionOptions, string>;
     exportResponses: Action<ExportResponsesOptions, Buffer>;
     getBearerToken: Action<{
         clientId: string;
         clientSecret: string;
         scope: string;
     }, string>;
+    getContactsImportStatus: Action<{
+        directoryId: string;
+        importId: string;
+        mailingListId: string;
+        bearerToken?: string;
+    }, ContactsImportStatusResponse>;
+    getContactsImportSummary: Action<{
+        directoryId: string;
+        importId: string;
+        mailingListId: string;
+        bearerToken?: string;
+    }, ContactsImportSummaryResponse>;
+    getDistribution: Action<{
+        distributionId: string;
+        surveyId: string;
+        bearerToken?: string;
+    }, Distribution>;
     getResponseExportFile: Action<{
         surveyId: string;
         fileId: string;
@@ -32,6 +116,40 @@ type Connection = {
         surveyId: string;
         bearerToken?: string;
     }, FileProgressResponse>;
+    importContacts: Action<StartContactsImportOptions, ContactsImportSummaryResponse>;
+    listDistributions: Action<{
+        surveyId: string;
+        distributionRequestType: DistributionRequestType;
+        mailingListId: string;
+        sendStartDate: Date;
+        sendEndDate: Date;
+        skipToken?: string;
+        useNewPaginationScheme?: boolean;
+        pageSize?: number;
+        bearerToken?: string;
+    }, {
+        elements: Distribution[];
+        nextPage: string | null;
+    }>;
+    listLibraryMessages: Action<{
+        libraryId: string;
+        category?: string;
+        offset?: number;
+        bearerToken?: string;
+    }, {
+        elements: {
+            id: string;
+            description: string;
+            category: string;
+        }[];
+        nextPage: string | null;
+    }>;
+    startContactsImport: Action<StartContactsImportOptions, {
+        id: string;
+        contacts: Array<Contact>;
+        tracking: object;
+        status: string;
+    }>;
     startResponseExport: Action<ExportResponsesOptions, {
         progressId: string;
         percentComplete: number;
@@ -67,15 +185,152 @@ type ExportResponsesOptions = {
     sortByLastModifiedDate?: boolean;
     bearerToken?: string;
 };
+type CreateDistributionOptions = {
+    libraryId: string;
+    messageId: string;
+    messageText?: string;
+    mailingListId: string;
+    contactId?: string;
+    transactionBatchId?: string;
+    fromEmail: string;
+    replyToEmail?: string;
+    fromName: string;
+    subject: string;
+    surveyId: string;
+    expirationDate: Date;
+    type: 'Individual' | 'Multiple' | 'Anonymous';
+    embeddedData?: Record<string, string>;
+    sendDate: Date;
+    bearerToken?: string;
+};
+type CreateReminderOptions = {
+    distributionId: string;
+    libraryId: string;
+    messageId: string;
+    fromEmail: string;
+    replyToEmail?: string;
+    fromName: string;
+    subject: string;
+    sendDate: Date;
+    embeddedData?: Record<string, string>;
+    bearerToken?: string;
+};
 type FileProgressResponse = {
     fileId: string;
     percentComplete: number;
     status: string;
     continuationToken?: string;
 };
+type StartContactsImportOptions = {
+    directoryId: string;
+    mailingListId: string;
+    contacts: Array<Contact>;
+    transactionMeta?: {
+        fields: string[];
+        batchId: string;
+    };
+    bearerToken?: string;
+};
+type ContactsImportSummaryResponse = {
+    percentComplete: number;
+    contacts: {
+        count: {
+            added: number;
+            updated: number;
+            failed: number;
+        };
+    };
+    invalidEmails: string[];
+    transactions: {
+        count: {
+            created: number;
+        };
+    };
+    status: string;
+};
+type ContactsImportStatusResponse = {
+    percentComplete: number;
+    contacts: {
+        count: {
+            added: number;
+            updated: number;
+            failed: number;
+        };
+    };
+    transactions: {
+        count: {
+            created: number;
+        };
+    };
+    status: string;
+};
+type DistributionOptions = {
+    directoryId: string;
+    mailingListName: string;
+    ownerId: string;
+    prioritizeListMetadata?: boolean;
+    contacts: Array<Contact>;
+    transactionMeta?: {
+        fields: string[];
+        batchId: string;
+    };
+    libraryId: string;
+    distributionMessageId: string;
+    distributionMessageText?: string;
+    reminderMessageId: string;
+    transactionBatchId?: string;
+    fromEmail: string;
+    replyToEmail?: string;
+    fromName: string;
+    subject: string;
+    surveyId: string;
+    expirationDate: Date;
+    type: 'Individual' | 'Multiple' | 'Anonymous';
+    embeddedData?: Record<string, string>;
+    sendDate: Date;
+    bearerToken?: string;
+};
 
 declare const createConnection: ConnectionFactory;
 
+/**
+ *  Create Distribution
+ *
+ * Implements Create Distribution
+ * @see https://api.qualtrics.com/573e3f0a94888-create-distribution
+ */
+declare const createDistribution: ActionFactory<CreateDistributionOptions, string>;
+
+/**
+ *  Create Mailing List
+ *
+ * Implements Create Mailing List
+ * @see https://api.qualtrics.com/3f633e4cea6cd-create-mailing-list
+ */
+declare const createMailingList: ActionFactory<{
+    directoryId: string;
+    name: string;
+    ownerId: string;
+    prioritizeListMetadata?: boolean;
+    bearerToken?: string;
+}, string>;
+
+/**
+ *  Create Reminder
+ *
+ * Implements Create Reminder Distribution
+ * @see https://api.qualtrics.com/764630bb0633a-create-reminder-distribution
+ */
+declare const createReminder: ActionFactory<CreateReminderOptions, string>;
+
+/**
+ * Export Survey Response File
+ *
+ * Implements Survey Response File Export end to end
+ * @see https://api.qualtrics.com/u9e5lh4172v0v-survey-response-export-guide
+ */
+declare const distributeSurveys: ActionFactory<DistributionOptions, string>;
+
 /**
  * Export Survey Response File
  *
@@ -96,6 +351,44 @@ declare const getBearerToken: ActionFactory<{
     scope: string;
 }, string>;
 
+/**
+ *  Get Contacts Import Status
+ *
+ * Implements Get Transaction Contacts Import Status
+ * @see https://api.qualtrics.com/c5d22705b1d45-get-transaction-contacts-import-status
+ */
+declare const getContactsImportStatus: ActionFactory<{
+    directoryId: string;
+    importId: string;
+    mailingListId: string;
+    bearerToken?: string;
+}, ContactsImportStatusResponse>;
+
+/**
+ *  Confirm Add Contacts
+ *
+ * Implements Create Transaction Contacts Import
+ * @see https://api.qualtrics.com/6f0480b307053-get-transaction-contacts-import-summary
+ */
+declare const getContactsImportSummary: ActionFactory<{
+    directoryId: string;
+    importId: string;
+    mailingListId: string;
+    bearerToken?: string;
+}, ContactsImportSummaryResponse>;
+
+/**
+ *  Get Distribution
+ *
+ * Implements Get Distribution
+ * @see https://api.qualtrics.com/f5b1d8775d803-get-distribution
+ */
+declare const getDistribution: ActionFactory<{
+    distributionId: string;
+    surveyId: string;
+    bearerToken?: string;
+}, Distribution>;
+
 /**
  * Get Response Export File
  *
@@ -120,6 +413,68 @@ declare const getResponseExportFile: ActionFactory<{
     bearerToken?: string;
 }, Buffer>;
 
+/**
+ * Import Contacts
+ *
+ * Implements import contacts end to end
+ * @see https://api.qualtrics.com/1ac99fba8ca5b-contact-imports
+ */
+declare const importContacts: ActionFactory<StartContactsImportOptions, ContactsImportSummaryResponse>;
+
+/**
+ * List Distributions
+ *
+ * Implements List Distributions
+ * @see https://api.qualtrics.com/234bb6b16cf6d-list-distributions
+ */
+declare const listDistributions: ActionFactory<{
+    surveyId: string;
+    distributionRequestType: DistributionRequestType;
+    mailingListId: string;
+    sendStartDate: Date;
+    sendEndDate: Date;
+    skipToken?: string;
+    useNewPaginationScheme?: boolean;
+    pageSize?: number;
+    bearerToken?: string;
+}, {
+    elements: Distribution[];
+    nextPage: string | null;
+}>;
+
+/**
+ * List Library Messages
+ *
+ * Implements List Library Messages
+ * @see https://api.qualtrics.com/1d60a66b340fa-list-library-messages
+ */
+declare const listLibraryMessages: ActionFactory<{
+    libraryId: string;
+    category?: string;
+    offset?: number;
+    bearerToken?: string;
+}, {
+    elements: {
+        id: string;
+        description: string;
+        category: string;
+    }[];
+    nextPage: string | null;
+}>;
+
+/**
+ *  Start Contacts Import
+ *
+ * Implements Create Transaction Contacts Import
+ * @see https://api.qualtrics.com/bab13356ac724-create-transaction-contacts-import
+ */
+declare const startContactsImport: ActionFactory<StartContactsImportOptions, {
+    id: string;
+    contacts: Array<Contact>;
+    tracking: object;
+    status: string;
+}>;
+
 /**
  *  Start Response Export
  *
@@ -138,4 +493,4 @@ declare const startResponseExport: ActionFactory<ExportResponsesOptions, {
  */
 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 };
+export { type Action, type ActionFactory, type Connection, type ConnectionFactory, type ConnectionOptions, type Contact, type ContactsImportStatusResponse, type ContactsImportSummaryResponse, type CreateDistributionOptions, type CreateReminderOptions, type Distribution, type DistributionOptions, type DistributionRequestType, type ExportResponsesOptions, type Failure, type FileProgressResponse, type ResponseFormat, type Result, type StartContactsImportOptions, type Success, createConnection, createDistribution, createMailingList, createReminder, distributeSurveys, exportResponses, getBearerToken, getContactsImportStatus, getContactsImportSummary, getDistribution, getResponseExportFile, getResponseExportProgress, importContacts, listDistributions, listLibraryMessages, startContactsImport, startResponseExport, testConnection };