extension.yaml

# Copyright 2019 Google LLC
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#    https://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

name: mailchimp-firebase-sync
version: 0.5.4
specVersion: v1beta

displayName: Manage Marketing with Mailchimp
description: Syncs user data with a Mailchimp audience for sending personalized email marketing campaigns.

license: Apache-2.0

sourceUrl: https://github.com/mailchimp/Firebase/tree/master/
releaseNotesUrl: https://github.com/mailchimp/Firebase/tree/master/CHANGELOG.md

author:
  authorName: Mailchimp
  url: https://mailchimp.com

contributors:
  - authorName: Lauren Long
    url: https://github.com/laurenzlong
  - authorName: Chris Bianca
    email: chris@csfrequency.com
    url: https://github.com/chrisbianca
  - authorName: Invertase
    email: oss@invertase.io
    url: https://github.com/invertase
  - authorName: Amr Desouky
    email: desoukya@gmail.com
    url: https://github.com/desoukya
  - authorName: Bart Breen
    email: bart.breen@twobulls.com
    url: https://github.com/barticus

billingRequired: true

externalServices:
  - name: Mailchimp
    pricingUri: https://mailchimp.com/pricing

resources:
  - name: addUserToList
    type: firebaseextensions.v1beta.function
    description:
      Listens for new user accounts (as managed by Firebase Authentication),
      then automatically adds the new user to your specified MailChimp audience.
    properties:
      location: ${LOCATION}
      runtime: nodejs18
      eventTrigger:
        eventType: providers/firebase.auth/eventTypes/user.create
        resource: projects/${PROJECT_ID}

  - name: removeUserFromList
    type: firebaseextensions.v1beta.function
    description:
      Listens for existing user accounts to be deleted (as managed by Firebase
      Authentication), then automatically removes them from your specified
      MailChimp audience.
    properties:
      location: ${LOCATION}
      runtime: nodejs18
      eventTrigger:
        eventType: providers/firebase.auth/eventTypes/user.delete
        resource: projects/${PROJECT_ID}

  - name: memberTagsHandler
    type: firebaseextensions.v1beta.function
    description:
      Member Tags provide the ability to associate "metadata" or "labels" with a Mailchimp subscriber.
      The memberTagsHandler function listens for Firestore write events based on specified config path,
      then automatically classifies the document data as Mailchimp subscriber tags.
    properties:
      location: ${LOCATION}
      runtime: nodejs18
      eventTrigger:
        eventType: providers/cloud.firestore/eventTypes/document.write
        resource: projects/${param:PROJECT_ID}/databases/(default)/documents/${param:MAILCHIMP_MEMBER_TAGS_WATCH_PATH}/{documentId}

  - name: mergeFieldsHandler
    type: firebaseextensions.v1beta.function
    description:
      Merge fields provide the ability to create new properties that can be associated with Mailchimp subscriber.
      The mergeFieldsHandler function listens for Firestore write events based on specified config path,
      then automatically populates the Mailchimp subscriber's respective merge fields.
    properties:
      location: ${LOCATION}
      runtime: nodejs18
      eventTrigger:
        eventType: providers/cloud.firestore/eventTypes/document.write
        resource: projects/${param:PROJECT_ID}/databases/(default)/documents/${param:MAILCHIMP_MERGE_FIELDS_WATCH_PATH}/{documentId}

  - name: memberEventsHandler
    type: firebaseextensions.v1beta.function
    description:
      Member events are Mailchimp specific activity events that can be created and associated with a predefined action.
      The memberEventsHandler function Listens for Firestore write events based on specified config path,
      then automatically uses the document data to create a Mailchimp event on the subscriber's profile
      which can subsequently trigger automation workflows.
    properties:
      location: ${LOCATION}
      runtime: nodejs18
      eventTrigger:
        eventType: providers/cloud.firestore/eventTypes/document.write
        resource: projects/${param:PROJECT_ID}/databases/(default)/documents/${param:MAILCHIMP_MEMBER_EVENTS_WATCH_PATH}/{documentId}

params:
  - param: LOCATION
    label: Cloud Functions location
    description: >-
      Where do you want to deploy the functions created for this extension?
    type: select
    options:
      - label: Iowa (us-central1)
        value: us-central1
      - label: South Carolina (us-east1)
        value: us-east1
      - label: Northern Virginia (us-east4)
        value: us-east4
      - label: Los Angeles (us-west2)
        value: us-west2
      - label: Salt Lake City (us-west3)
        value: us-west3
      - label: Las Vegas (us-west4)
        value: us-west4
      - label: Warsaw (europe-central2)
        value: europe-central2
      - label: Belgium (europe-west1)
        value: europe-west1
      - label: London (europe-west2)
        value: europe-west2
      - label: Frankfurt (europe-west3)
        value: europe-west3
      - label: Zurich (europe-west6)
        value: europe-west6
      - label: Hong Kong (asia-east2)
        value: asia-east2
      - label: Tokyo (asia-northeast1)
        value: asia-northeast1
      - label: Osaka (asia-northeast2)
        value: asia-northeast2
      - label: Seoul (asia-northeast3)
        value: asia-northeast3
      - label: Mumbai (asia-south1)
        value: asia-south1
      - label: Jakarta (asia-southeast2)
        value: asia-southeast2
      - label: Montreal (northamerica-northeast1)
        value: northamerica-northeast1
      - label: Sao Paulo (southamerica-east1)
        value: southamerica-east1
      - label: Sydney (australia-southeast1)
        value: australia-southeast1
    default: us-central1
    required: true
    immutable: true

  - param: MAILCHIMP_API_KEY
    label: Mailchimp OAuth Token
    description: >-
      To obtain a Mailchimp OAuth Token, click
      [here](https://firebase.mailchimp.com/index.html).
    type: string
    example: a1b2c3d4e5f6g7
    required: true

  - param: MAILCHIMP_AUDIENCE_ID
    label: Audience ID
    description: >-
      What is the Mailchimp Audience ID to which you want to subscribe new
      users? To find your Audience ID: visit https://admin.mailchimp.com/lists,
      click on the desired audience or create a new audience, then select
      **Settings**. Look for **Audience ID** (for example, `27735fc60a`).
    type: string
    example: 1ab2345c67
    required: true

  - param: MAILCHIMP_RETRY_ATTEMPTS
    label: Mailchimp Retry Attempts
    description: >-
      The number of attempts to retry operation against Mailchimp. 
      Race conditions can occur between user creation events and user update events, and this allows the extension to retry operations that failed transiently. 
      Currently this is limited to 404 responses for removeUserFromList, memberTagsHandler, mergeFieldsHandler and memberEventsHandler calls.
    type: string
    validationRegex: "^[0-9]$"
    validationErrorMessage: The number of attempts must be an integer value between 0 and 9.
    default: "2"
    required: true

  - param: MAILCHIMP_CONTACT_STATUS
    label: Contact status
    description: >-
      When the extension adds a new user to the Mailchimp audience, what is
      their initial status? This value can be `subscribed` or `pending`.
      `subscribed` means the user can receive campaigns; `pending` means the
      user still needs to opt-in to receive campaigns.
    type: select
    options:
      - label: Subscribed
        value: subscribed
      - label: Pending
        value: pending
    default: subscribed
    required: true

  - param: MAILCHIMP_MEMBER_TAGS_WATCH_PATH
    label: Firebase Member Tags Watch Path
    description: The Firestore collection to watch for member tag changes
    type: string
    example: registrations
    default: _unused_
    required: true

  - param: MAILCHIMP_MEMBER_TAGS_CONFIG
    type: string
    label: Firebase Member Tags Config
    description: >-
      Provide a configuration mapping in JSON format indicating which Firestore event(s) to listen for and associate as Mailchimp member tags.


      Required Fields:

      1) `memberTags` - The Firestore document fields(s) to retrieve data from and classify as subscriber tags in Mailchimp. Acceptable data types include:
          
          - `Array<String>` - The extension will lookup the values in the provided fields and update the subscriber's member tags with the respective data values. The format of each string can be any valid [JMES Path query](https://jmespath.org/). e.g. ["primaryTags", "additionalTags", "tags.primary"]

          - `Array<Object>` - An extended object configuration is supported with the following fields:
              - `documentPath` - (required) The path to the field in the document containing tag/s, as a string. The format can be any valid [JMES Path query](https://jmespath.org/). e.g. "primaryTags", "tags.primary".

      2) `subscriberEmail` - The Firestore document field capturing the user email as is recognized by Mailchimp


      Configuration Example:

      ```json

      {
        "memberTags": ["domainKnowledge", "jobTitle"],
        "subscriberEmail": "emailAddress"
      }

      ```


      Or via equivalent extended syntax:

      ```json

      {
        "memberTags": [{ "documentPath": "domainKnowledge" }, { "documentPath": "jobTitle" }],
        "subscriberEmail": "emailAddress"
      } 

      ```

      Based on the sample configuration, if the following Firestore document is provided:

      ```json

      {
        "firstName": "..",
        "lastName": "..",
        "phoneNumber": "..",
        "courseName": "..",
        "emailAddress": "..", // The config property 'subscriberEmail' maps to this document field
        "jobTitle": "..", // The config property 'memberTags' maps to this document field
        "domainKnowledge": "..", // The config property 'memberTags' maps to this document field
        "activity": []
      } 

      ```

      Any data associated with the mapped fields (i.e. `domainKnowledge` and `jobTitle`) will be considered Member Tags and the Mailchimp user's profile will be updated accordingly.

      For complex documents such as:

      ```json

      {
        "emailAddress": "..", // The config property 'subscriberEmail' maps to this document field
        "meta": {
          "tags": [{
            "label": "Red",
            "value": "red"
          },{
            "label": "Team 1",
            "value": "team1"
          }]
        }
      } 

      ```

      A configuration of the following will allow for the tag values of "red", "team1" to be sent to Mailchimp:

      ```json

      {
        "memberTags": [{ "documentPath": "meta.tags[*].value" }],
        "subscriberEmail": "emailAddress"
      } 

      ```

      NOTE: To disable this cloud function listener, provide an empty JSON config `{}`.

    required: true
    default: "{}"

  - param: MAILCHIMP_MERGE_FIELDS_WATCH_PATH
    label: Firebase Merge Fields Watch Path
    description: The Firestore collection to watch for merge field changes
    type: string
    example: registrations
    default: _unused_
    required: true

  - param: MAILCHIMP_MERGE_FIELDS_CONFIG
    type: string
    label: Firebase Merge Fields Config
    description: >-
      Provide a configuration mapping in JSON format indicating which Firestore event(s) to listen for and associate as Mailchimp merge fields.


      Required Fields:

      1) `mergeFields` - JSON mapping representing the Firestore document fields to associate with Mailchimp Merge Fields. The key format can be any valid [JMES Path query](https://jmespath.org/) as a string. The value must be the name of a Mailchimp Merge Field as a string, or an object with the following properties:

          - `mailchimpFieldName` - (required) The name of the Mailchimp Merge Field to map to, e.g. "FNAME". Paths are allowed, e.g. "ADDRESS.addr1" will map to an "ADDRESS" object.

          - `typeConversion` - (optional) Whether to apply a type conversion to the value found at documentPath. Valid options: 
              
              - `none`: no conversion is applied.

              - `timestampToDate`: Converts from a [Firebase Timestamp](https://firebase.google.com/docs/reference/android/com/google/firebase/Timestamp) to YYYY-MM-DD format (UTC).
              
              - `stringToNumber`: Converts to a number.

          - `when` - (optional) When to send the value of the field to Mailchimp. Options are "always" (which will send the value of this field on _any_ change to the document, not just this field) or "changed". Default is "changed".

      2) `statusField` - An optional configuration setting for syncing the users mailchimp status. Properties are:

          - `documentPath` - (required) The path to the field in the document containing the users status, as a string. The format can be any valid [JMES Path query](https://jmespath.org/). e.g. "status", "meta.status".

          - `statusFormat` - (optional) Indicates the format that the status field is. The options are:
              - `"string"` - The default, this will sync the value from the status field as is, with no modification.
              - `"boolean"` - This will check if the value is truthy (e.g. true, 1, "subscribed"), and if so will resolve the status to "subscribed", otherwise it will resolve to "unsubscribed".

      3) `subscriberEmail` - The Firestore document field capturing the user email as is recognized by Mailchimp


      Configuration Example:

      ```json

      {
        "mergeFields": {
          "firstName": "FNAME",
          "lastName": "LNAME",
          "phoneNumber": "PHONE"
        },
        "subscriberEmail": "emailAddress"
      }

      ```

      Or via equivalent extended syntax:

      ```json

      {
        "mergeFields": {
          "firstName": { "mailchimpFieldName": "FNAME" },
          "lastName":{ "mailchimpFieldName": "LNAME" },
          "phoneNumber": { "mailchimpFieldName": "PHONE", "when": "changed" }
        },
        "subscriberEmail": "emailAddress"
      } 

      ```


      Based on the sample configuration, if the following Firestore document is provided:

      ```json

      {
        "firstName": "..", // The config property FNAME maps to this document field
        "lastName": "..", // The config property LNAME maps to this document field
        "phoneNumber": "..", // The config property PHONE maps to this document field
        "emailAddress": "..", // The config property "subscriberEmail" maps to this document field
        "jobTitle": "..", 
        "domainKnowledge": "..",
        "activity": []
      } 

      ```


      Any data associated with the mapped fields (i.e. firstName, lastName, phoneNumber) will be considered Merge Fields and the Mailchimp user's profile will be updated accordingly.

      If there is a requirement to always send the firstName and lastName values, the `"when": "always"` configuration option can be set on those fields, like so:

      ```json

      {
        "mergeFields": {
          "firstName": { "mailchimpFieldName": "FNAME", "when": "always" },
          "lastName":{ "mailchimpFieldName": "LNAME", "when": "always" },
          "phoneNumber": { "mailchimpFieldName": "PHONE", "when": "changed" }
        },
        "subscriberEmail": "emailAddress"
      } 

      ```

      This can be handy if Firebase needs to remain the source or truth or if the extension has been installed after data is already in the collection and there is a data migration period.

      If the users status is also captured in the Firestore document, the status can be updated in Mailchimp by using the following configuration:

      ```json

      {
        "statusField": {
          "documentPath": "meta.status",
          "statusFormat": "string",
        },
        "subscriberEmail": "emailAddress"
      } 

      ```

      This can be as well, or instead of, the `mergeFields` configuration property being set.

      NOTE: To disable this cloud function listener, provide an empty JSON config `{}`.

    required: true
    default: "{}"

  - param: MAILCHIMP_MEMBER_EVENTS_WATCH_PATH
    label: Firebase Member Events Watch Path
    description: The Firestore collection to watch for member event changes
    type: string
    example: registrations
    default: _unused_
    required: true

  - param: MAILCHIMP_MEMBER_EVENTS_CONFIG
    type: string
    label: Firebase Member Events Config
    description: >-
      Provide a configuration mapping in JSON format indicating which Firestore event(s) to listen for and associate as Mailchimp merge events.


      Required Fields:

      1) `memberEvents` - The Firestore document fields(s) to retrieve data from and classify as member events in Mailchimp. Acceptable data types include:

        - `Array<String>` - The extension will lookup the values (mailchimp event names) in the provided fields and post those events to Mailchimp on the subscriber's activity feed. The format can be any valid [JMES Path query](https://jmespath.org/). e.g. ["events", "meta.events"]

        - `Array<Object>` - An extended object configuration is supported with the following fields:
            - `documentPath` - (required) The path to the field in the document containing events. The format can be any valid [JMES Path query](https://jmespath.org/). e.g. "events", "meta.events".

      2) `subscriberEmail` - The Firestore document field capturing the user email as is recognized by Mailchimp


      Configuration Example:

      ```json

      {
        "memberEvents": [
          "activity"
        ],
        "subscriberEmail": "emailAddress"
      } 

      ```

      Or via equivalent extended syntax:

      ```json

      {
        "memberEvents": [{ "documentPath": "activity" }],
        "subscriberEmail": "emailAddress"
      } 

      ```

      Based on the sample configuration, if the following Firestore document is provided:

      ```json

      {
        "firstName": "..",
        "lastName": "..",
        "phoneNumber": "..",
        "courseName": "..",
        "jobTitle": "..", 
        "domainKnowledge": "..",
        "emailAddress": "..", // The config property "subscriberEmail" maps to this document field
        "activity": ["send_welcome_email"] // The config property "memberTags" maps to this document field
      } 

      ```

      Any data associated with the mapped fields (i.e. `activity`) will be considered events and the Mailchimp user's profile will be updated accordingly.

      For complex documents such as:

      ```json

      {
        "emailAddress": "..", // The config property 'subscriberEmail' maps to this document field
        "meta": {
          "events": [{
            "title": "Registered",
            "date": "2021-10-08T00:00:00Z"
          },{
            "title": "Invited Friend",
            "date": "2021-10-09T00:00:00Z"
          }]
        }
      } 

      ```

      A configuration of the following will allow for the events of "Registered", "Invited Friend" to be sent to Mailchimp:

      ```json

      {
        "memberEvents": [{ "documentPath": "meta.events[*].title" }],
        "subscriberEmail": "emailAddress"
      } 

      ```

      NOTE: To disable this cloud function listener, provide an empty JSON config `{}`.

    required: true
    default: "{}"